Merge pull request #1879 from EliahKagan/manpages

Improve Sphinx role usage, including linking Git manpages

Author: Byron

doc/source/conf.py

@@ -3,29 +3,28 @@
 #
 # This file is execfile()d with the current directory set to its containing dir.
 #
-# The contents of this file are pickled, so don't put values in the namespace
-# that aren't pickleable (module imports are okay, they're removed automatically).
+# The contents of this file are pickled, so don't put values in the namespace that
+# aren't pickleable (module imports are okay, they're removed automatically).
 #
-# Note that not all possible configuration values are present in this
-# autogenerated file.
+# Note that not all possible configuration values are present in this autogenerated
+# file.
 #
-# All configuration values have a default; values that are commented out
-# serve to show the default.
+# All configuration values have a default; values that are commented out serve to show
+# the default.
 
-import sys
 import os
+import sys
 
-# If your extensions are in another directory, add it here. If the directory
-# is relative to the documentation root, use os.path.abspath to make it
-# absolute, like shown here.
+# If your extensions are in another directory, add it here. If the directory is relative
+# to the documentation root, use os.path.abspath to make it absolute, like shown here.
 # sys.path.append(os.path.abspath('.'))
 sys.path.insert(0, os.path.abspath("../.."))
 
 # General configuration
 # ---------------------
 
-# Add any Sphinx extension module names here, as strings. They can be extensions
-# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+# Add any Sphinx extension module names here, as strings. They can be extensions coming
+# with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = ["sphinx.ext.autodoc", "sphinx.ext.doctest"]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -44,9 +43,8 @@
 project = "GitPython"
 copyright = "Copyright (C) 2008, 2009 Michael Trier and contributors, 2010-2015 Sebastian Thiel"
 
-# The version info for the project you're documenting, acts as replacement for
-# |version| and |release|, also used in various other places throughout the
-# built documents.
+# The version info for the project you're documenting, acts as replacement for |version|
+# and |release|, also used in various other places throughout the built documents.
 #
 # The short X.Y version.
 with open(os.path.join(os.path.dirname(__file__), "..", "..", "VERSION")) as fd:
@@ -55,8 +53,8 @@
 # The full version, including alpha/beta/rc tags.
 release = VERSION
 
-# The language for content autogenerated by Sphinx. Refer to documentation
-# for a list of supported languages.
+# The language for content autogenerated by Sphinx. Refer to documentation for a list of
+# supported languages.
 # language = None
 
 # There are two options for replacing |today|: either, you set today to some
@@ -68,8 +66,8 @@
 # List of documents that shouldn't be included in the build.
 # unused_docs = []
 
-# List of directories, relative to source directory, that shouldn't be searched
-# for source files.
+# List of directories, relative to source directory, that shouldn't be searched for
+# source files.
 exclude_trees = ["build"]
 
 # The reST default role (used for this markup: `text`) to use for all documents.
@@ -78,58 +76,59 @@
 # If true, '()' will be appended to :func: etc. cross-reference text.
 # add_function_parentheses = True
 
-# If true, the current module name will be prepended to all description
-# unit titles (such as .. function::).
+# If true, the current module name will be prepended to all description unit titles
+# (such as .. function::).
 # add_module_names = True
 
-# If true, sectionauthor and moduleauthor directives will be shown in the
-# output. They are ignored by default.
+# If true, sectionauthor and moduleauthor directives will be shown in the output.
+# They are ignored by default.
 # show_authors = False
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = "sphinx"
 
+manpages_url = "https://git-scm.com/docs/{page}"
+
 
 # Options for HTML output
 # -----------------------
 
 html_theme = "sphinx_rtd_theme"
 html_theme_options = {}
 
-# The name for this set of Sphinx documents.  If None, it defaults to
-# "<project> v<release> documentation".
+# The name for this set of Sphinx documents.
+# If None, it defaults to "<project> v<release> documentation".
 # html_title = None
 
-# A shorter title for the navigation bar.  Default is the same as html_title.
+# A shorter title for the navigation bar. Default is the same as html_title.
 # html_short_title = None
 
-# The name of an image file (relative to this directory) to place at the top
-# of the sidebar.
+# The name of an image file (relative to this directory) to place at the top of the
+# sidebar.
 # html_logo = None
 
-# The name of an image file (within the static path) to use as favicon of the
-# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
-# pixels large.
+# The name of an image file (within the static path) to use as favicon of the docs.
+# This file should be a Windows icon file (.ico) being 16x16 or 32x32 pixels large.
 # html_favicon = None
 
-# Add any paths that contain custom static files (such as style sheets) here,
-# relative to this directory. They are copied after the builtin static files,
-# so a file named "default.css" will overwrite the builtin "default.css".
+# Add any paths that contain custom static files (such as style sheets) here, relative
+# to this directory. They are copied after the builtin static files, so a file named
+# "default.css" will overwrite the builtin "default.css".
 html_static_path = []
 
-# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
-# using the given strftime format.
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, using the
+# given strftime format.
 # html_last_updated_fmt = '%b %d, %Y'
 
-# If true, SmartyPants will be used to convert quotes and dashes to
-# typographically correct entities.
+# If true, SmartyPants will be used to convert quotes and dashes to typographically
+# correct entities.
 # html_use_smartypants = True
 
 # Custom sidebar templates, maps document names to template names.
 # html_sidebars = {}
 
-# Additional templates that should be rendered to pages, maps page names to
-# template names.
+# Additional templates that should be rendered to pages, maps page names to template
+# names.
 # html_additional_pages = {}
 
 # If false, no module index is generated.
@@ -144,9 +143,9 @@
 # If true, the reST sources are included in the HTML build as _sources/<name>.
 # html_copy_source = True
 
-# If true, an OpenSearch description file will be output, and all pages will
-# contain a <link> tag referring to it.  The value of this option must be the
-# base URL from which the finished HTML is served.
+# If true, an OpenSearch description file will be output, and all pages will contain a
+# <link> tag referring to it. The value of this option must be the base URL from which
+# the finished HTML is served.
 # html_use_opensearch = ''
 
 # If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
@@ -171,8 +170,8 @@
     ("index", "GitPython.tex", "GitPython Documentation", "Michael Trier", "manual"),
 ]
 
-# The name of an image file (relative to this directory) to place at the top of
-# the title page.
+# The name of an image file (relative to this directory) to place at the top of the
+# title page.
 # latex_logo = None
 
 # For "manual" documents, if this is true, then toplevel headings are parts,

git/cmd.py

@@ -901,7 +901,8 @@ def working_dir(self) -> Union[None, PathLike]:
     def version_info(self) -> Tuple[int, ...]:
         """
         :return: Tuple with integers representing the major, minor and additional
-            version numbers as parsed from ``git version``. Up to four fields are used.
+            version numbers as parsed from :manpage:`git-version(1)`. Up to four fields
+            are used.
 
             This value is generated on demand and is cached.
         """
@@ -1038,9 +1039,9 @@ def execute(
             3. Deeper descendants do not receive signals, though they may sometimes
                terminate as a consequence of their parent processes being killed.
             4. `kill_after_timeout` uses ``SIGKILL``, which can have negative side
-               effects on a repository. For example, stale locks in case of ``git gc``
-               could render the repository incapable of accepting changes until the lock
-               is manually removed.
+               effects on a repository. For example, stale locks in case of
+               :manpage:`git-gc(1)` could render the repository incapable of accepting
+               changes until the lock is manually removed.
 
         :param with_stdout:
             If ``True``, default ``True``, we open stdout on the created process.

git/config.py

@@ -270,7 +270,7 @@ def get_config_path(config_level: Lit_config_levels) -> str:
 class GitConfigParser(cp.RawConfigParser, metaclass=MetaParserBuilder):
     """Implements specifics required to read git style configuration files.
 
-    This variation behaves much like the ``git config`` command, such that the
+    This variation behaves much like the :manpage:`git-config(1)` command, such that the
     configuration will be read on demand based on the filepath given during
     initialization.
 

git/db.py

@@ -59,7 +59,7 @@ def partial_to_complete_sha_hex(self, partial_hexsha: str) -> bytes:
         :raise gitdb.exc.BadObject:
 
         :note:
-            Currently we only raise :class:`~gitdb.exc.BadObject` as git does not
+            Currently we only raise :exc:`~gitdb.exc.BadObject` as git does not
             communicate ambiguous objects separately.
         """
         try:

git/diff.py

@@ -222,8 +222,8 @@ def diff(
             to be read and diffed.
 
         :param kwargs:
-            Additional arguments passed to ``git diff``, such as ``R=True`` to swap both
-            sides of the diff.
+            Additional arguments passed to :manpage:`git-diff(1)`, such as ``R=True`` to
+            swap both sides of the diff.
 
         :return:
             A :class:`DiffIndex` representing the computed diff.
@@ -590,7 +590,7 @@ def _index_from_patch_format(cls, repo: "Repo", proc: Union["Popen", "Git.AutoIn
             The repository we are operating on.
 
         :param proc:
-            ``git diff`` process to read from
+            :manpage:`git-diff(1)` process to read from
             (supports :class:`Git.AutoInterrupt <git.cmd.Git.AutoInterrupt>` wrapper).
 
         :return: