Generate man page via Sphinx (#891)

.circleci/config.yml

@@ -91,7 +91,7 @@ jobs:
       - checkout
       - run:
           name: Run tests against Python 3.10 and git 2.33.1 (with building docs)
-          command: PYTHON_VERSION=3.10 GIT_VERSION=2.33.1 BUILD_SPHINX_DOCS=true CHECK_PY_DOCS_UP_TO_DATE=true bash ci/tox/ci-run.sh
+          command: PYTHON_VERSION=3.10 GIT_VERSION=2.33.1 BUILD_SPHINX_HTML=true CHECK_DOCS_UP_TO_DATE=true bash ci/tox/ci-run.sh
       - store_test_results:
           path: test-results/
       - store_artifacts:

.gitignore

@@ -10,6 +10,10 @@ build/
 coverage.xml
 dist/
 docs/html/
+# See https://stackoverflow.com/a/21643672 for why not just `docs/man/`
+docs/man/**
+!docs/man/git-machete.1
+docs/man-compare
 *.egg-info/
 .eggs/
 htmlcov/

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2017-2019 Paweł Lipski
+Copyright (c) 2017-2023 VirtusLab
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

MANIFEST.in

@@ -1,4 +1,5 @@
 include LICENSE
 
-# Needed for the Homebrew formula to install the completion scripts correctly
+# As for now, used just by the Homebrew formula
 recursive-include completion *
+include           docs/man/git-machete.1

RELEASE_NOTES.md

@@ -5,6 +5,7 @@
 - added: `--ignore-if-missing` flag to `git machete github retarget-pr` command
 - added: `--branch=<branch>` option to `git machete github retarget-pr` command
 - fixed: `github anno-prs` no longer assumes that local branch and its remote counterpart share the same name
+- fixed: `git machete --help` displays a man page (instead of crashing with `No manual entry for git-machete`) when git-machete is installed via Homebrew
 
 ## New in git-machete 3.16.3
 

ci/checks/enforce-consistent-style-for-fork-point.sh

@@ -6,6 +6,6 @@ self_dir=$(cd "$(dirname "$0")" &>/dev/null; pwd -P)
 self_name=$(basename "$0")
 source "$self_dir"/utils.sh
 
-if git grep '[fF]orkpoint' -- :!**/$self_name; then
+if git grep -n '[fF]orkpoint' -- :!**/$self_name; then
   die "Please use 'fork point' or 'Fork point' or 'fork_point' instead of 'forkpoint' or 'Forkpoint'."
 fi

ci/checks/enforce-consistent-style-for-github.sh

@@ -6,6 +6,6 @@ self_dir=$(cd "$(dirname "$0")" &>/dev/null; pwd -P)
 source "$self_dir"/utils.sh
 self_name=$(basename "$0")
 
-if git grep Github -- :!**/$self_name; then
+if git grep -n Github -- :!**/$self_name; then
   die "Please use 'GitHub' instead of 'Github'."
 fi

ci/checks/enforce-release-notes-up-to-date.sh

@@ -3,7 +3,7 @@
 set -e -o pipefail -u
 
 current_version=$(python3 setup.py --version)
-release_notes_version=$(sed '3!d' RELEASE_NOTES.md | grep -Eo '(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)')
+release_notes_version=$(sed '3!d' RELEASE_NOTES.md | grep -Eo '(0|[1-9][0-9]*)(\.(0|[1-9][0-9]*))+')
 
 if [[ $current_version != "$release_notes_version" ]]; then
   echo "Please update RELEASE_NOTES.md! Current version: $current_version, latest version in RELEASE_NOTES.md (line 3): $release_notes_version."

ci/checks/prohibit-double-backticks-in-py.sh

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 
-if git grep '``' -- '*.py'; then
+if git grep -n '``' -- '*.py'; then
   echo
   echo 'Formatting provided by git_machete.utils.fmt only accepts single backticks (`...`).'
   echo 'Double backticks (``...``) are probably a copy-paste from .rst files.'

ci/checks/prohibit-markdown-links-in-rst.sh

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+
+if git grep -n '\[.*\](.*)' -- '*.rst'; then
+  echo
+  echo 'ReStructuredText uses a different syntax for links than Markdown: not [text](url) but `text <url>`_'
+  exit 1
+fi

ci/checks/prohibit-single-backtick-in-rst.sh

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 
-if git grep -e ' `[^`]' --and --not -e 'https://' -- '*.rst'; then
+if git grep -n -e ' `[^`]' --and --not -e 'https://' -- '*.rst'; then
   echo
   echo 'Single backticks (`...`) are notoriously confusing in ReStructuredText: unlike in Markdown, they correspond to italics, not verbatim text.'
   echo 'Use the somewhat more unambiguous *...* for italics, and double backticks (``...``) for verbatim text.'

ci/checks/run-all-checks.sh

@@ -26,6 +26,7 @@ enforce-shell-scripts-pass-shellcheck.sh
 enforce-version-bumped.sh
 prohibit-deploy-step-in-circleci.sh
 prohibit-double-backticks-in-py.sh
+prohibit-markdown-links-in-rst.sh
 prohibit-single-backtick-in-rst.sh
 prohibit-strings-split-without-delimiter.sh
 prohibit-strings-with-backslash-continuation.sh

ci/tox/.env-sample

@@ -3,7 +3,7 @@ GIT_VERSION=2.25.0  # note that generally the older the git version, the faster
 PYTHON_VERSION=3.8
 
 # Vars for `docker-compose run`
-BUILD_SPHINX_DOCS=false
-CHECK_PY_DOCS_UP_TO_DATE=false
+BUILD_SPHINX_HTML=false
+CHECK_DOCS_UP_TO_DATE=false
 CHECK_COVERAGE=false
 CHECK_PEP8=false

ci/tox/build-context/run.sh

@@ -7,7 +7,7 @@ if ! ( [ -f setup.py ] && grep -q "name='git-machete'" setup.py ); then
   exit 1
 fi
 
-env | sort | head -3
+env | sort | head -4
 
 set -x
 
@@ -17,19 +17,19 @@ else
   TOX_ENV_LIST="mypy-py${PYTHON_VERSION/./},py${PYTHON_VERSION/./}"
 fi
 
-if [[ $BUILD_SPHINX_DOCS = true ]]; then
-  TOX_ENV_LIST="$TOX_ENV_LIST,sphinx-docs"
+if [[ $BUILD_SPHINX_HTML = true ]]; then
+  TOX_ENV_LIST="$TOX_ENV_LIST,sphinx-html"
 fi
 
-if [[ $CHECK_PY_DOCS_UP_TO_DATE = true ]]; then
-  TOX_ENV_LIST="$TOX_ENV_LIST,check-py-docs"
+if [[ $CHECK_DOCS_UP_TO_DATE = true ]]; then
+  TOX_ENV_LIST="$TOX_ENV_LIST,check-py-docs,check-sphinx-man"
 fi
 
 if [[ $CHECK_PEP8 = true ]]; then
   TOX_ENV_LIST="$TOX_ENV_LIST,pep8,isort-check"
 fi
 
-tox -e $TOX_ENV_LIST
+tox -e "$TOX_ENV_LIST"
 
 $PYTHON setup.py install --user
 PATH=$PATH:$HOME/.local/bin/

ci/tox/docker-compose.yml

@@ -9,8 +9,8 @@ services:
         - git_version=${GIT_VERSION:-0.0.0}
         - python_version=${PYTHON_VERSION:-0.0.0}
     environment:
-      - BUILD_SPHINX_DOCS=${BUILD_SPHINX_DOCS:-false}
-      - CHECK_PY_DOCS_UP_TO_DATE=${CHECK_PY_DOCS_UP_TO_DATE:-false}
+      - BUILD_SPHINX_HTML=${BUILD_SPHINX_HTML:-false}
+      - CHECK_DOCS_UP_TO_DATE=${CHECK_DOCS_UP_TO_DATE:-false}
       - CHECK_COVERAGE=${CHECK_COVERAGE:-false}
       - CHECK_PEP8=${CHECK_PEP8:-false}
     volumes:

docs/enforce-docs-up-to-date.sh → docs/enforce-py-docs-up-to-date.sh

@@ -6,6 +6,6 @@ current_docs=$(<git_machete/generated_docs.py)
 generated_docs=$(python docs/generate_py_docs.py)
 
 if [[ "$current_docs" != "$generated_docs" ]]; then
-  echo "Command line docs are not up-to-date. Please regenerate docs via 'tox -e py-docs'"
+  echo "Command line docs are not up-to-date with the sources. Please regenerate docs via 'tox -e py-docs'."
   exit 1
 fi

docs/enforce-sphinx-man-up-to-date.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+
+set -e -o pipefail -u
+
+./docs/generate-sphinx-man.sh docs/man-compare
+# Skip `.TH "GIT-MACHETE" "1" "<date>" "" "git-machete"` lines as they might differ just on the date
+if ! cmp <(grep -v '^\.TH' docs/man/git-machete.1) <(grep -v '^\.TH' docs/man-compare/git-machete.1); then
+  echo "Man page is not up-to-date with the sources. Please regenerate via 'tox -e sphinx-man'."
+  exit 1
+fi

docs/generate-sphinx-html.sh

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+
+set -e -o pipefail -u
+
+target_dir=$1
+
+# `-t html` is needed for the conditionally rendered sections
+sphinx-build -W --keep-going -b html -t html docs/source "$target_dir"
+
+# To view the generated file(s), use
+#   open     docs/html/index.html  # macOS
+#   xdg-open docs/html/index.html  # Linux

docs/generate-sphinx-man.sh

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+
+set -e -o pipefail -u
+
+target_dir=$1
+
+# `-t man` is needed for the conditionally rendered sections
+sphinx-build -W --keep-going -b man -t man docs/source "$target_dir"
+
+# To view the generated file, use
+#   groff -man -Tascii < docs/man/git-machete.1 | less -r