Changes how docs are built

sobolevn · May 4, 2021 · ca500fa · ca500fa
1 parent ce73d9d
commit ca500fa
Show file tree

Hide file tree

Showing 53 changed files with 221 additions and 85 deletions.
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
@@ -9,7 +9,7 @@ Here's how it's done:
 4. You can also spell check your code using 'aspell -c {filename}'
 5. If you are adding or changing features, please add tests that cover the new behavior (in addition to the unchanged behavior if appropriate)
 6. Make sure that all tests pass
-7. Change the .ronn file(s) in man/man*/ to document your changes if appropriate 
+7. Change the .md file(s) in man/man*/ to document your changes if appropriate
    (regenerating man pages with 'make build-man' is optional)
 8. Add an entry to CHANGELOG.md explaining the change briefly and, if appropriate, referring to the related issue #
 

diff --git a/.github/workflows/github-pages.yml b/.github/workflows/github-pages.yml
@@ -12,10 +12,8 @@ jobs:
     steps:
     - uses: actions/checkout@v2
 
-    - name: Build manuals
-      run: |
-        make build-man
-        cp -r man/ docs/man
+    - name: Build docs
+      run: make docs
 
     - name: Deploy to Pages
       uses: JamesIves/[email protected]

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -90,7 +90,7 @@ This will copy the hooks from utils/hooks into .git/hooks/pre-commit and .git/ho
 
 5. Add an entry to CHANGELOG.md, referring to the related issue # if appropriate
 
-6. Change the .ronn file(s) in man/man1 and man/man7 to document your changes if appropriate
+6. Change the `man` source file(s) (we write them in markdown) in `man/man1` and `man/man7` to document your changes if appropriate
 
 7. Now, add all your files to the commit with `git add --all` and commit changes with `git commit`.
    Write a good commit message which explains your work
@@ -130,32 +130,15 @@ output from commands.
 To create a new release, (you'll first need permission to commit to the repo, of course):
 
 Update the content of `CHANGELOG.md` for the release (this should be a matter of changing headers),
-and update the version string in `src/version.sh`.  Then, when you `commit` these changes,
-the git-hooks described below will perform most of the steps needed for the github release.
+and update the version string in `src/version.sh`.
 
-So a lot of the release process is defined in the `git`-hooks and `.travis.yml`.
+When creating a commit inside the `master` branch (it is usually a documentation and changelog update with the version bump inside `src/version.sh`).
 
-When creating a commit inside the `master` branch (it is usually a documentation and changelog update with the version bump inside `src/version.sh`) the
-pre-commit and post-commit hooks will trigger three events.
+Then, push your code to GitHub. It will start the CI.
 
-- `pre-commit`: run the test suite will be locally
+After all the checks have executed, GitHub Actions will test and build releases for specific platforms.
 
-- `pre-commit`: generate and update the manuals and add them to the current commit with `make build-man`
-
-- `post-commit`: a GitHub Action will update the `gh-pages` branch to match the `docs` folder in the `master` branch, which will push updated manuals to the [git-secret site][git-secret-site].
-
-- `post-commit`: new `git` tag (such as v0.3.1) will be automatically created if the version is changed, using something like
-
-```bash
-if [[ "$NEWEST_TAG" != "v${SCRIPT_VERSION}" ]]; then
-  git tag -a "v${SCRIPT_VERSION}" -m "version $SCRIPT_VERSION"
-fi
-```
-
-After all the above hooks have executed, travis-ci will test and build releases for specific platforms
-(see  https://bintray.com/sobolevn/deb/git-secret, https://bintray.com/sobolevn/rpm/git-secret, etc).
-
-While travis is doing it's building and testing, finish the release on github by pushing the new tag with:
+While CI is doing it's building and testing, finish the release on github by pushing the new tag with:
 
 ```bash
 git push --tags

diff --git a/Makefile b/Makefile
@@ -22,13 +22,11 @@ build: git-secret
 
 .PHONY: install
 install:
-	chmod +x "./utils/install.sh"; sync; \
-	"./utils/install.sh" "${DESTDIR}${PREFIX}"
+	${SHELL} ./utils/install.sh "${DESTDIR}${PREFIX}"
 
 .PHONY: uninstall
 uninstall:
-	chmod +x "./utils/uninstall.sh"; sync; \
-	"./utils/uninstall.sh" "${DESTDIR}${PREFIX}"
+	${SHELL} ./utils/uninstall.sh "${DESTDIR}${PREFIX}"
 
 #
 # Testing and linting:
@@ -39,10 +37,9 @@ uninstall:
 # Using a sub-shell we get the raw *nix paths, e.g. /c/Something
 .PHONY: test
 test: clean build
-	chmod +x "./utils/tests.sh"; sync; \
 	export SECRET_PROJECT_ROOT="$(shell echo $${PWD})"; \
 	export PATH="$(shell echo $${PWD})/vendor/bats-core/bin:$(shell echo $${PWD}):$(shell echo $${PATH})"; \
-	"./utils/tests.sh"
+	${SHELL} ./utils/tests.sh
 
 # We use this script in CI and you can do this too!
 # What happens here?
@@ -69,7 +66,7 @@ lint-shell:
 		-w /code \
 		-e SHELLCHECK_OPTS='-s bash -S warning -a' \
 		--rm koalaman/shellcheck \
-		$$(find src .ci utils tests -type f \
+		$$(find src .ci utils tests docs -type f \
 			-name '*.sh' -o -name '*.bash' -o -name '*.bats')
 
 .PHONY: lint-docker
@@ -87,30 +84,44 @@ lint-docker:
 lint: lint-shell lint-docker
 
 #
-# Manuals:
+# Manuals and docs:
 #
 
 .PHONY: clean-man
 clean-man:
-	find "man/" -type f -name "*.roff" -delete
+	find "man/" -type f ! -name "*.md" -delete
 
 .PHONY: build-man
-build-man: clean-man git-secret
+build-man: git-secret
 	# Prepare:
-	touch man/*/*.ronn
+	touch man/*/*.md
 
 	# Build docker image:
 	docker pull msoap/ruby-ronn
 
 	# Do the manual generation:
-	GITSECRET_VERSION=`./git-secret --version` docker run \
+	export GITSECRET_VERSION="$$(./git-secret --version)" && docker run \
 		--volume="$${PWD}:/code" \
 		-w /code \
 		--rm msoap/ruby-ronn \
 		ronn --roff \
 			--organization=sobolevn \
 			--manual="git-secret $${GITSECRET_VERSION}" \
-			man/*/*.ronn
+			man/*/*.md
+
+.PHONY: build-docs
+build-docs: build-man
+	${SHELL} docs/create_posts.sh
+
+.PHONY: docs
+docs: build-docs
+	docker pull jekyll/jekyll
+	docker run \
+		--volume="$${PWD}/docs:/code" \
+		-w /code \
+		-p 4000:4000 \
+		--rm jekyll/jekyll \
+		jekyll serve --safe --strict_front_matter
 
 #
 # Packaging:

diff --git a/docs/Gemfile b/docs/Gemfile
@@ -0,0 +1,6 @@
+source "https://rubygems.org"
+
+group :jekyll_plugins do
+  gem "jekyll", ">= 3.6.3"
+  gem "jekyll-seo-tag", "~> 2.7.1"
+end
diff --git a/docs/Gemfile.lock b/docs/Gemfile.lock
@@ -0,0 +1,70 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.7.0)
+      public_suffix (>= 2.0.2, < 5.0)
+    colorator (1.1.0)
+    concurrent-ruby (1.1.7)
+    em-websocket (0.5.2)
+      eventmachine (>= 0.12.9)
+      http_parser.rb (~> 0.6.0)
+    eventmachine (1.2.7)
+    ffi (1.14.2)
+    forwardable-extended (2.6.0)
+    http_parser.rb (0.6.0)
+    i18n (1.8.5)
+      concurrent-ruby (~> 1.0)
+    jekyll (4.2.0)
+      addressable (~> 2.4)
+      colorator (~> 1.0)
+      em-websocket (~> 0.5)
+      i18n (~> 1.0)
+      jekyll-sass-converter (~> 2.0)
+      jekyll-watch (~> 2.0)
+      kramdown (~> 2.3)
+      kramdown-parser-gfm (~> 1.0)
+      liquid (~> 4.0)
+      mercenary (~> 0.4.0)
+      pathutil (~> 0.9)
+      rouge (~> 3.0)
+      safe_yaml (~> 1.0)
+      terminal-table (~> 2.0)
+    jekyll-sass-converter (2.1.0)
+      sassc (> 2.0.1, < 3.0)
+    jekyll-seo-tag (2.7.1)
+      jekyll (>= 3.8, < 5.0)
+    jekyll-watch (2.2.1)
+      listen (~> 3.0)
+    kramdown (2.3.0)
+      rexml
+    kramdown-parser-gfm (1.1.0)
+      kramdown (~> 2.0)
+    liquid (4.0.3)
+    listen (3.3.3)
+      rb-fsevent (~> 0.10, >= 0.10.3)
+      rb-inotify (~> 0.9, >= 0.9.10)
+    mercenary (0.4.0)
+    pathutil (0.16.2)
+      forwardable-extended (~> 2.6)
+    public_suffix (4.0.6)
+    rb-fsevent (0.10.4)
+    rb-inotify (0.10.1)
+      ffi (~> 1.0)
+    rexml (3.2.3)
+    rouge (3.26.0)
+    safe_yaml (1.0.5)
+    sassc (2.4.0)
+      ffi (~> 1.9)
+    terminal-table (2.0.0)
+      unicode-display_width (~> 1.1, >= 1.1.1)
+    unicode-display_width (1.7.0)
+
+PLATFORMS
+  x86_64-linux-musl
+
+DEPENDENCIES
+  jekyll (>= 3.6.3)
+  jekyll-seo-tag (~> 2.7.1)
+
+BUNDLED WITH
+   2.2.2
diff --git a/docs/_config.yml b/docs/_config.yml
@@ -11,7 +11,7 @@ email: [email protected]
 description: > # this means to ignore newlines until "baseurl:"
   A bash-tool to store your private data inside a git repository.
 baseurl: "" # the subpath of your site, e.g. /blog
-url: "http://sobolevn.github.io" # the base hostname & protocol for your site
+url: "git-secret.io" # the base hostname & protocol for your site
 
 # Github links:
 github_username: sobolevn

diff --git a/docs/_includes/header.html b/docs/_includes/header.html
@@ -15,11 +15,9 @@
 
       <div class="trigger">
         <!-- Place this tag where you want the button to render. -->
-        <a class="github-button"
-           href="https://github.com/sobolevn/git-secret#git-secret"
-           data-style="mega" aria-label="Download sobolevn/git-secret on GitHub">
-           Download
-         </a>
+        <a class="github-button" href="https://github.com/sobolevn/git-secret" data-icon="octicon-star" data-size="large" data-show-count="true" aria-label="Star git-secret on GitHub">
+          Star
+        </a>
       </div>
     </div>
 
@@ -33,3 +31,6 @@
   </nav>
 
 </header>
+
+<!-- Required for GitHub buttons. -->
+<script async defer src="https://buttons.github.io/buttons.js"></script>
diff --git a/docs/_posts/2020-09-20-git-secret-add.md → docs/_posts/2021-05-04-git-secret-add.md b/docs/_posts/2020-09-20-git-secret-add.md → docs/_posts/2021-05-04-git-secret-add.md
@@ -1,7 +1,7 @@
 ---
 layout: post
 title:  'git-secret-add'
-date:   2020-09-20 15:12:56 -0400
+date:   2021-05-04 12:15:29 +0300
 permalink: git-secret-add
 categories: command
 ---
@@ -10,7 +10,7 @@ git-secret-add - starts to track added files.
 
 ## SYNOPSIS
 
-    git secret add [-i] <pathspec>...
+    git secret add [-v] [-i] <pathspec>...
 
 
 ## DESCRIPTION
@@ -30,6 +30,7 @@ folder using the SECRETS_DIR environment variable.
 
 ## OPTIONS
 
+    -v  - verbose, shows extra information.
     -i  - does nothing, adding paths to .gitignore is now the default behavior.
     -h  - shows this help.
 

diff --git a/docs/_posts/2020-09-20-git-secret-cat.md → docs/_posts/2021-05-04-git-secret-cat.md b/docs/_posts/2020-09-20-git-secret-cat.md → docs/_posts/2021-05-04-git-secret-cat.md
@@ -1,7 +1,7 @@
 ---
 layout: post
 title:  'git-secret-cat'
-date:   2020-09-20 15:12:56 -0400
+date:   2021-05-04 12:15:29 +0300
 permalink: git-secret-cat
 categories: command
 ---

diff --git a/docs/_posts/2020-09-20-git-secret-changes.md → docs/_posts/2021-05-04-git-secret-changes.md b/docs/_posts/2020-09-20-git-secret-changes.md → docs/_posts/2021-05-04-git-secret-changes.md
@@ -1,7 +1,7 @@
 ---
 layout: post
 title:  'git-secret-changes'
-date:   2020-09-20 15:12:56 -0400
+date:   2021-05-04 12:15:29 +0300
 permalink: git-secret-changes
 categories: command
 ---

diff --git a/docs/_posts/2020-09-20-git-secret-clean.md → docs/_posts/2021-05-04-git-secret-clean.md b/docs/_posts/2020-09-20-git-secret-clean.md → docs/_posts/2021-05-04-git-secret-clean.md
@@ -1,7 +1,7 @@
 ---
 layout: post
 title:  'git-secret-clean'
-date:   2020-09-20 15:12:56 -0400
+date:   2021-05-04 12:15:29 +0300
 permalink: git-secret-clean
 categories: command
 ---

diff --git a/docs/_posts/2020-09-20-git-secret-hide.md → docs/_posts/2021-05-04-git-secret-hide.md b/docs/_posts/2020-09-20-git-secret-hide.md → docs/_posts/2021-05-04-git-secret-hide.md
@@ -1,7 +1,7 @@
 ---
 layout: post
 title:  'git-secret-hide'
-date:   2020-09-20 15:12:56 -0400
+date:   2021-05-04 12:15:29 +0300
 permalink: git-secret-hide
 categories: command
 ---

diff --git a/docs/_posts/2020-09-20-git-secret-init.md → docs/_posts/2021-05-04-git-secret-init.md b/docs/_posts/2020-09-20-git-secret-init.md → docs/_posts/2021-05-04-git-secret-init.md
@@ -1,7 +1,7 @@
 ---
 layout: post
 title:  'git-secret-init'
-date:   2020-09-20 15:12:56 -0400
+date:   2021-05-04 12:15:29 +0300
 permalink: git-secret-init
 categories: command
 ---

diff --git a/...posts/2020-09-20-git-secret-killperson.md → ...posts/2021-05-04-git-secret-killperson.md b/...posts/2020-09-20-git-secret-killperson.md → ...posts/2021-05-04-git-secret-killperson.md
@@ -1,7 +1,7 @@
 ---
 layout: post
 title:  'git-secret-killperson'
-date:   2020-09-20 15:12:56 -0400
+date:   2021-05-04 12:15:29 +0300
 permalink: git-secret-killperson
 categories: command
 ---

diff --git a/docs/_posts/2020-09-20-git-secret-list.md → docs/_posts/2021-05-04-git-secret-list.md b/docs/_posts/2020-09-20-git-secret-list.md → docs/_posts/2021-05-04-git-secret-list.md
@@ -1,7 +1,7 @@
 ---
 layout: post
 title:  'git-secret-list'
-date:   2020-09-20 15:12:56 -0400
+date:   2021-05-04 12:15:29 +0300
 permalink: git-secret-list
 categories: command
 ---

diff --git a/docs/_posts/2020-09-20-git-secret-remove.md → docs/_posts/2021-05-04-git-secret-remove.md b/docs/_posts/2020-09-20-git-secret-remove.md → docs/_posts/2021-05-04-git-secret-remove.md
@@ -1,7 +1,7 @@
 ---
 layout: post
 title:  'git-secret-remove'
-date:   2020-09-20 15:12:56 -0400
+date:   2021-05-04 12:15:29 +0300
 permalink: git-secret-remove
 categories: command
 ---

diff --git a/docs/_posts/2020-09-20-git-secret-reveal.md → docs/_posts/2021-05-04-git-secret-reveal.md b/docs/_posts/2020-09-20-git-secret-reveal.md → docs/_posts/2021-05-04-git-secret-reveal.md
@@ -1,7 +1,7 @@
 ---
 layout: post
 title:  'git-secret-reveal'
-date:   2020-09-20 15:12:56 -0400
+date:   2021-05-04 12:15:29 +0300
 permalink: git-secret-reveal
 categories: command
 ---

diff --git a/docs/_posts/2020-09-20-git-secret-tell.md → docs/_posts/2021-05-04-git-secret-tell.md b/docs/_posts/2020-09-20-git-secret-tell.md → docs/_posts/2021-05-04-git-secret-tell.md
@@ -1,7 +1,7 @@
 ---
 layout: post
 title:  'git-secret-tell'
-date:   2020-09-20 15:12:56 -0400
+date:   2021-05-04 12:15:29 +0300
 permalink: git-secret-tell
 categories: command
 ---
@@ -14,12 +14,16 @@ git-secret-tell - adds a person, who can access private data.
 
 
 ## DESCRIPTION
-`git-secret-tell` receives one or more email addresses as an input, searches for the `gpg`-key in the `gpg`
+`git-secret tell` receives one or more email addresses as an input, searches for the `gpg`-key in the `gpg`
 `homedir` by these emails, then imports the corresponding public key into `git-secret`'s inner keychain. 
 From this moment this person can encrypt new files with the keyring which contains their key,
 but they cannot decrypt the old files, which were already encrypted without their key. 
 The files should be re-encrypted with the new keyring by someone who has the unencrypted files.
 
+Because `git-secret tell` works with only email addresses, it will exit with an error if you have
+multiple keys in your keychain with specified email addresses, or if one of the specified emails 
+is already associated with a key in the git-secret keychain.
+
 Versions of `git-secret tell` after 0.3.2 will warn about keys that are expired, revoked, or otherwise invalid,
 and also if multiple keys are found for a single email address.