René's URL Explorer Experiment

Title: Improve Sphinx role usage, including linking Git manpages by EliahKagan · Pull Request #1879 · gitpython-developers/GitPython · GitHub

Open Graph Title: Improve Sphinx role usage, including linking Git manpages by EliahKagan · Pull Request #1879 · gitpython-developers/GitPython

X Title: Improve Sphinx role usage, including linking Git manpages by EliahKagan · Pull Request #1879 · gitpython-developers/GitPython

Description: 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).

Open Graph Description: 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 ...

X Description: 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 ...

Opengraph URL: https://github.com/gitpython-developers/GitPython/pull/1879

X: @github

direct link

Domain: github.com

Links:

Viewport: width=device-width