Improve Sphinx role usage, including linking Git manpages #1879

EliahKagan · 2024-03-16T06:46:53Z

This makes various improvements to how docstrings use Sphinx roles (and a bit of other related cleanup), detailed in the individual commit messages.

The most significant, which motivated this pull request, is using the :manpage: role for references to Git subcommands and other Git topics for which there is a manual page. The effect, when reading the built HTML documentation, is to make it so mentions of specific Git commands are linked references to their manpages in Git's official online reference. This was achieved by a combination of two changes:

c5a29a9: Setting manpages_url = "https://git-scm.com/docs/{page}" in doc/source/conf.py so that reStructuredText such as :manpage:`git-clone(1)`, when rendered in HTML, links to the corresponding online manpage (for that example, https://git-scm.com/docs/git-clone). This was feasible because there were no manual page references, attempts to make them, or areas where it would be useful to make them, other than to Git manual pages. So that the Git website doesn't have documentation for commands that aren't part of Git is not a problem for setting manpages_url this way.
d8ab99c: Turn all mentions of specific Git subcommands and other Git topics that have a manpage into that form. For subcommands the existing forms were mostly like git-clone or like ``git clone`` (the latter of which was mainly present due to my having used it in some places in earlier revisions). In both cases it seems the context is preserved or enhanced by turning them into :manpage:`git-clone(1)`. There were a small number of cases where a full URL had been used. Note that when URLs linked to specific sections (and meant to), I did not replace those, since this syntax does not support that. Also, when more of a command was shown, e.g., ``git remote set-url``, I of course did not replace that, which would lose information about the more specific action (sub-sub command?) of set-url.

(Of course, git-clone(1) is just one example, and this is in no way limited to the clone subcommand specifically.)

One example of what this looks like can be seen in the rendered Commit.iter_items docstring from the pull request preview build. Others can be identified by looking at the changes adding the :manpage: role in d8ab99c (and then looked up in the PR preview build if desired).

This is mostly a change to comments.

(This is grouped as a general option since it is technically classified as such, even though it currently only affects HTML output.)

In docstrings within the git module. This makes text of the same general form as, e.g. git-rev-parse or ``git rev-parse`` or URLs that link directly to a documentation page equivalent to a manpage or that link to the first section where preceding material is trivial... ...instead be in the form: :manpage:`git-rev-parse(1)` with variations as appropriate, for example changing gitglossary(7) to :manpage:`gitglossary(7)` and making other changes accordingly, such as adjusting phrasing and the use of hyphens in a small number of cases. Together with c5a29a9, which made such references linkify to the' official online documentation for Git, this makes it so that when git subcommands are mentioned in docstrings, the Sphinx autodoc generated documentation in the API Reference page now renders them as links to the relevant documentation page. Links to specific sections where it matters or potentially matters that it goes to that section are not replaced. In particular, links to specific entries in gitglossary(7) are not replaced. To do this properly would involve adding a new Sphinx role for it, which would work well in the rendered documentation but could be unclear when the documentation is read in docstrings appearing in the code.

This could also be written automatically by labeling it with the :manpage: role, but it doesn't seem to be an actual manpage, so I have not done that.

I am still not using the :manpage: role for this because it points to a specific section, which that role does not support, and it is important that it go to that specific section. (See d8ab99c for details.)

Note that this intentionally does *not* include some all-caps class attributes that are not really constants: - Git.GIT_PYTHON_GIT_EXECUTABLE is set by refresh functions, including on subsequent calls, which is an important and documented part of what those functions do. (Also, it is set automatically from an enviroment variable, which is not constant across runs; that it could not even in principle be replaced by a specific literal value is a further reason it is not a constant.) - The Git.USE_SHELL attribute is a more ambiguous case. It is given a literal value (False) which it preferably remains. But setting it has been documented as something users can do (in the changelog, and later in regard to setting it being a deprecated operation). The first of these is decisively not a constant even under a loose definition, while the second is less clear. I've kept both with the :attr: role.

There are only a three cases where a specific RFC is mentioned. Only one is in parse_date and the others are elsewhere.

Rather than the more general :class: role that was used for them.

Byron

That's a fantastic improvement, thanks so much!

I tried the new look of the manpage links and like them both rendered and in restructured text. An improvement all around!

EliahKagan added 10 commits March 15, 2024 12:30

Put Sphinx conf.py in the same style as other code

0969db9

This is mostly a change to comments.

Link Sphinx manpage references to online Git docs

c5a29a9

(This is grouped as a general option since it is technically classified as such, even though it currently only affects HTML output.)

Remove a spurious extra backtick from a docstring

7f1675d

Add a missing Sphinx reference to a class

e883293

Use more official link to index-format documentation

d271a84

This could also be written automatically by labeling it with the :manpage: role, but it doesn't seem to be an actual manpage, so I have not done that.

Use current main official link to git-clone URLS doc

ca95c42

I am still not using the :manpage: role for this because it points to a specific section, which that role does not support, and it is important that it go to that specific section. (See d8ab99c for details.)

Fix parse_date docstring spacing; use RFC role

6626117

There are only a three cases where a specific RFC is mentioned. Only one is in parse_date and the others are elsewhere.

Use the :exc: role for exceptions

a957ae7

Rather than the more general :class: role that was used for them.

EliahKagan marked this pull request as ready for review March 16, 2024 07:01

Byron approved these changes Mar 16, 2024

View reviewed changes

Byron merged commit 0a609b9 into gitpython-developers:main Mar 16, 2024
26 checks passed

EliahKagan deleted the manpages branch March 16, 2024 13:58

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Improve Sphinx role usage, including linking Git manpages #1879

Improve Sphinx role usage, including linking Git manpages #1879

EliahKagan commented Mar 16, 2024 •

edited

Loading

Byron left a comment

Improve Sphinx role usage, including linking Git manpages #1879

Improve Sphinx role usage, including linking Git manpages #1879

Conversation

EliahKagan commented Mar 16, 2024 • edited Loading

Byron left a comment

Choose a reason for hiding this comment

EliahKagan commented Mar 16, 2024 •

edited

Loading