Issue #719: Unify sphinx documentation formatting for config section (#…

…723)

RELEASE_NOTES.md

@@ -7,6 +7,7 @@
 - fixed: removed stack trace when terminating `git machete` command prompt with `Ctrl+D`
 - added: support for Python 3.11
 - added: machete config key `machete.traverse.push` that controls default behavior of `traverse` command
+- improved: formatting of the `config` section in the sphinx documentation
 
 ## New in git-machete 3.12.5
 

docs/generate_py_docs.py

@@ -1,4 +1,4 @@
-from bs4 import BeautifulSoup
+from bs4 import BeautifulSoup, Comment
 from docutils import core
 import os
 from os.path import isfile, join
@@ -26,6 +26,10 @@ def html2txt(html_: str):
     for tag in html_elements.select('style'):
         tag.decompose()
 
+    # remove comments
+    for comment in html_elements.findAll(string=lambda string: isinstance(string, Comment)):
+        comment.extract()
+
     # remove non-breaking spaces
     for tag in html_elements.select('td'):
         if tag.text == u'\xa0':
@@ -139,11 +143,29 @@ def skip_or_replace_unparseable_directives(rst_: str) -> str:
 
 
 def resolve_includes(rst_: str, docs_source_path_: str) -> str:
-    matches = re.findall(r'(.*)\.\. include:: (.*)', rst_)
-    for indent_, match in matches:
+    matches = re.findall(r'(.*)\.\. include:: (.*)\n(.* :(.*): ([0-9]*)\n)?(.* :(.*): ([0-9]*)\n)?', rst_)
+    # example matches:
+    #     .. include:: status_config_key.rst
+    #
+    #     .. include:: status_config_key.rst
+    #         :start-line: 2
+    #
+    #     .. include:: status_config_key.rst
+    #         :start-line: 2
+    #         :end-line: 6
+    for indent_, match, option_1_str, option_1, option_1_value, option_2_str, option_2, option_2_value in matches:
         with open(f'{docs_source_path_}/{match}', 'r') as handle:
-            include_text = handle.read()
-        rst_ = rst_.replace(f'{indent_}.. include:: {match}', indent(dedent(include_text), indent_))
+            include_text = handle.readlines()
+        text_to_replace = f'{indent_}.. include:: {match}'
+        start_line, end_line = 0, len(include_text)
+        if option_1 == 'start-line':
+            start_line = int(option_1_value)
+            text_to_replace += f'\n{option_1_str}'
+        if option_2 == 'end-line':
+            end_line = int(option_2_value)
+            text_to_replace += f'{option_2_str}'
+        include_text = include_text[start_line:end_line]
+        rst_ = rst_.replace(text_to_replace, indent(dedent(''.join(include_text)), indent_), 1)
     return rst_
 
 

docs/source/cli_help/config.rst

@@ -2,16 +2,17 @@
 
 config
 ------
-Documentation about available ``git machete`` config keys and environment variables that change the command's default behavior.
+Documentation about available ``git machete`` git config keys and environment variables that change the command's default behavior.
 
 Note: ``config`` is not a command as such, just a help topic (there is no ``git machete config`` command).
 
-**Config keys:**
+**Git config keys:**
 
 ``machete.github.{remote,organization,repository}``:
     When executing ``git machete github <subcommand>`` command, the following will happen:
 
     .. include:: github_config_keys.rst
+        :start-line: 2
 
 ``machete.overrideForkPoint.<branch>.{to,whileDescendantOf}``:
     Executing ``git machete fork-point --override-to=<revision> [<branch>]`` sets up a fork point override for <branch>.
@@ -20,9 +21,11 @@ Note: ``config`` is not a command as such, just a help topic (there is no ``git
 
 ``machete.status.extraSpaceBeforeBranchName``:
     .. include:: status_config_key.rst
+        :start-line: 2
 
 ``machete.traverse.push``:
     .. include:: traverse_config_key.rst
+        :start-line: 2
 
 ``machete.worktree.useTopLevelMacheteFile``:
     The default value of this key is ``true``, which means that the path to machete definition file will be ``.git/machete``

docs/source/cli_help/status.rst

@@ -71,6 +71,7 @@ With ``--color=always``, git machete always emits colors and with ``--color=auto
     |
     m-<branch4>     # grey (merged to parent)
 
+.. include:: status_config_key.rst
 
 **Options:**
 
@@ -87,3 +88,5 @@ With ``--color=always``, git machete always emits colors and with ``--color=auto
 
 ``machete.status.extraSpaceBeforeBranchName``
     .. include:: status_config_key.rst
+        :start-line: 2
+        :end-line: 6

docs/source/cli_help/traverse.rst

@@ -116,6 +116,7 @@ Unlike with e.g. ``git rebase``, there is no special ``--continue`` flag, as ``t
 
 ``machete.traverse.push``
     .. include:: traverse_config_key.rst
+        :start-line: 2
 
 **Environment variables:**
 

docs/source/github_api_access.rst

@@ -1,4 +1,4 @@
- .. note::
+.. note::
 
     To allow GitHub API access for private repositories (and also to perform side-effecting actions like opening a PR,
     even in case of public repositories), a GitHub API token with ``repo`` scope is required, see https://github.com/settings/tokens.

docs/source/github_config_keys.rst

@@ -1,4 +1,4 @@
- .. note::
+.. note::
 
     GitHub API server URL will be inferred from ``git remote``.
     You can override this by setting the following git config keys:
@@ -20,3 +20,7 @@
             organization = <organization_name>
             repository = <repo_name>
             remote = <remote_name>
+
+..
+    Text order in this file is relevant, if you want to change something, find each ``.. include:: status_config_key.rst`` instance
+    and if the instance has ``start-line`` or ``end-line`` options provided, make sure that after changes the output text stays the same.

docs/source/status_config_key.rst

@@ -1,8 +1,8 @@
- .. note::
+.. note::
 
     To make it easier to select branch name from the ``status`` output on certain terminals
-    (e.g. `Alacritty <https://github.com/alacritty/alacritty>`_), you can add an extra
-    space between └─ and ``branch name`` by setting ``git config machete.status.extraSpaceBeforeBranchName true``.
+    (e.g. `Alacritty <https://github.com/alacritty/alacritty>`_), you can add an extra space between └─ and ``branch name``
+    by setting ``git config machete.status.extraSpaceBeforeBranchName true``.
 
     For example, by default the status is displayed as:
 
@@ -23,3 +23,7 @@
        ├─ feature_branch1
        │
        └─ feature_branch2
+
+..
+    Text order in this file is relevant, if you want to change something, find each ``.. include:: status_config_key.rst`` instance
+    and if the instance has ``start-line`` or ``end-line`` options provided, make sure that after changes the output text stays the same.

docs/source/traverse_config_key.rst

@@ -1,5 +1,9 @@
- .. note::
+.. note::
 
     To change the behaviour of ``git machete traverse`` command so that it doesn't push branches by default,
     you need to set config key ``git config machete.traverse.push false``.
     Configuration key value can be overridden by the presence of the flag.
+
+..
+    Text order in this file is relevant, if you want to change something, find each ``.. include:: status_config_key.rst`` instance
+    and if the instance has ``start-line`` or ``end-line`` options provided, make sure that after changes the output text stays the same.

git_machete/generated_docs.py

@@ -221,11 +221,11 @@
 
    """,
     "config": """
-        Documentation about available `git machete` config keys and environment variables that change the command's default behavior.
+        Documentation about available `git machete` git config keys and environment variables that change the command's default behavior.
 
         Note: `config` is not a command as such, just a help topic (there is no `git machete config` command).
 
-        <b>Config keys:</b>
+        <b>Git config keys:</b>
            `machete.github.{remote,organization,repository}`:
  
               When executing `git machete github <subcommand>` command, the following will happen:
@@ -257,8 +257,8 @@
            `machete.status.extraSpaceBeforeBranchName`:
 
               To make it easier to select branch name from the `status` output on certain terminals
-              (e.g. Alacritty), you can add an extra
-              space between └─ and `branch name` by setting `git config machete.status.extraSpaceBeforeBranchName true`.
+              (e.g. Alacritty), you can add an extra space between └─ and `branch name`
+              by setting `git config machete.status.extraSpaceBeforeBranchName true`.
 
               For example, by default the status is displayed as:
 
@@ -894,6 +894,28 @@
           m-<branch4>     # grey (merged to parent)
         </dim>
 
+        To make it easier to select branch name from the `status` output on certain terminals
+        (e.g. Alacritty), you can add an extra space between └─ and `branch name`
+        by setting `git config machete.status.extraSpaceBeforeBranchName true`.
+
+        For example, by default the status is displayed as:
+        <dim>
+          develop
+          │
+          ├─feature_branch1
+          │
+          └─feature_branch2
+        </dim>
+
+        With `machete.status.extraSpaceBeforeBranchName` config set to `true`:
+        <dim>
+          develop
+          │
+          ├─ feature_branch1
+          │
+          └─ feature_branch2
+        </dim>
+
         <b>Options:</b>
            <b>--color=WHEN</b>
               Colorize the output; WHEN can be `always`, `auto` (default; i.e. only if stdout is a terminal), or `never`.
@@ -907,26 +929,9 @@
 
         <b>Config keys:</b>
            `machete.status.extraSpaceBeforeBranchName`
-
               To make it easier to select branch name from the `status` output on certain terminals
-              (e.g. Alacritty), you can add an extra
-              space between └─ and `branch name` by setting `git config machete.status.extraSpaceBeforeBranchName true`.
-
-              For example, by default the status is displayed as:
-
-              develop
-              │
-              ├─feature_branch1
-              │
-              └─feature_branch2
-
-              With `machete.status.extraSpaceBeforeBranchName` config set to `true`:
-
-              develop
-              │
-              ├─ feature_branch1
-              │
-              └─ feature_branch2
+              (e.g. Alacritty), you can add an extra space between └─ and `branch name`
+              by setting `git config machete.status.extraSpaceBeforeBranchName true`.
 
    """,
     "traverse": """