Skip to content
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

Merged
merged 10 commits into from
Mar 16, 2024

Commits on Mar 15, 2024

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

    This is mostly a change to comments.
    EliahKagan committed Mar 15, 2024
    Configuration menu
    Copy the full SHA
    0969db9 View commit details
    Browse the repository at this point in the history
  2. 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.)
    EliahKagan committed Mar 15, 2024
    Configuration menu
    Copy the full SHA
    c5a29a9 View commit details
    Browse the repository at this point in the history
  3. Configuration menu
    Copy the full SHA
    7f1675d View commit details
    Browse the repository at this point in the history
  4. Configuration menu
    Copy the full SHA
    e883293 View commit details
    Browse the repository at this point in the history
  5. 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.
    EliahKagan committed Mar 15, 2024
    Configuration menu
    Copy the full SHA
    d8ab99c View commit details
    Browse the repository at this point in the history
  6. 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.
    EliahKagan committed Mar 15, 2024
    Configuration menu
    Copy the full SHA
    d271a84 View commit details
    Browse the repository at this point in the history
  7. 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.)
    EliahKagan committed Mar 15, 2024
    Configuration menu
    Copy the full SHA
    ca95c42 View commit details
    Browse the repository at this point in the history

Commits on Mar 16, 2024

  1. 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.
    EliahKagan committed Mar 16, 2024
    Configuration menu
    Copy the full SHA
    8543457 View commit details
    Browse the repository at this point in the history
  2. 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.
    EliahKagan committed Mar 16, 2024
    Configuration menu
    Copy the full SHA
    6626117 View commit details
    Browse the repository at this point in the history
  3. Use the :exc: role for exceptions

    Rather than the more general :class: role that was used for them.
    EliahKagan committed Mar 16, 2024
    Configuration menu
    Copy the full SHA
    a957ae7 View commit details
    Browse the repository at this point in the history