-
-
Notifications
You must be signed in to change notification settings - Fork 906
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Improve Sphinx role usage, including linking Git manpages #1879
Commits on Mar 15, 2024
-
Put Sphinx conf.py in the same style as other code
This is mostly a change to comments.
Configuration menu - View commit details
-
Copy full SHA for 0969db9 - Browse repository at this point
Copy the full SHA 0969db9View commit details -
Link Sphinx manpage references to online Git docs
(This is grouped as a general option since it is technically classified as such, even though it currently only affects HTML output.)
Configuration menu - View commit details
-
Copy full SHA for c5a29a9 - Browse repository at this point
Copy the full SHA c5a29a9View commit details -
Configuration menu - View commit details
-
Copy full SHA for 7f1675d - Browse repository at this point
Copy the full SHA 7f1675dView commit details -
Configuration menu - View commit details
-
Copy full SHA for e883293 - Browse repository at this point
Copy the full SHA e883293View commit details -
Use Sphinx manpage references where applicable
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.
Configuration menu - View commit details
-
Copy full SHA for d8ab99c - Browse repository at this point
Copy the full SHA d8ab99cView commit details -
Use more official link to index-format documentation
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.
Configuration menu - View commit details
-
Copy full SHA for d271a84 - Browse repository at this point
Copy the full SHA d271a84View commit details -
Use current main official link to git-clone URLS doc
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.)
Configuration menu - View commit details
-
Copy full SHA for ca95c42 - Browse repository at this point
Copy the full SHA ca95c42View commit details
Commits on Mar 16, 2024
-
Use :const: for constants that had the :attr: role
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.
Configuration menu - View commit details
-
Copy full SHA for 8543457 - Browse repository at this point
Copy the full SHA 8543457View commit details -
Fix parse_date docstring spacing; use RFC role
There are only a three cases where a specific RFC is mentioned. Only one is in parse_date and the others are elsewhere.
Configuration menu - View commit details
-
Copy full SHA for 6626117 - Browse repository at this point
Copy the full SHA 6626117View commit details -
Use the :exc: role for exceptions
Rather than the more general :class: role that was used for them.
Configuration menu - View commit details
-
Copy full SHA for a957ae7 - Browse repository at this point
Copy the full SHA a957ae7View commit details