From dfc509daee6ffd84f00cf384f009e70a9bfd0b15 Mon Sep 17 00:00:00 2001 From: Pradyun Gedam Date: Sun, 17 Jan 2021 17:11:54 +0000 Subject: Rewrite docs/conf.py This simplifies the Sphinx configuration and adds additional grouping and structure to the existing code as well. --- docs/html/conf.py | 358 ++++++++++++------------------------------------------ 1 file changed, 79 insertions(+), 279 deletions(-) (limited to 'docs/html/conf.py') diff --git a/docs/html/conf.py b/docs/html/conf.py index 7b5eb5a2d..7dece866d 100644 --- a/docs/html/conf.py +++ b/docs/html/conf.py @@ -1,13 +1,4 @@ -# pip documentation build configuration file, created by -# sphinx-quickstart on Tue Apr 22 22:08:49 2008 -# -# This file is execfile()d with the current directory set to its containing dir -# -# 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. +"""Sphinx configuration file for pip's documentation.""" import glob import os @@ -15,311 +6,120 @@ import pathlib import re import sys -on_rtd = os.environ.get('READTHEDOCS', None) == 'True' - +# Add the docs/ directory to sys.path, because pip_sphinxext.py is there. docs_dir = os.path.dirname(os.path.dirname(__file__)) -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. sys.path.insert(0, docs_dir) -# sys.path.append(os.path.join(os.path.dirname(__file__), '../')) -# -- General configuration ---------------------------------------------------- +# -- 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. -# extensions = ['sphinx.ext.autodoc'] extensions = [ - # native: - 'sphinx.ext.extlinks', - 'sphinx.ext.intersphinx', - # third-party: - 'myst_parser', - 'sphinx_inline_tabs', - 'sphinxcontrib.towncrier', - # in-tree: - 'pip_sphinxext', + # first-party extensions + "sphinx.ext.extlinks", + "sphinx.ext.intersphinx", + # our extensions + "pip_sphinxext", + # third-party extensions + "myst_parser", + "sphinx_copybutton", + "sphinx_inline_tabs", + "sphinxcontrib.towncrier", ] -# intersphinx -intersphinx_cache_limit = 0 -intersphinx_mapping = { - 'pypug': ('https://packaging.python.org/', None), - 'pypa': ('https://www.pypa.io/en/latest/', None), -} - - -# Add any paths that contain templates here, relative to this directory. -templates_path = [] - -# The suffix of source filenames. -source_suffix = '.rst' - -# The encoding of source files. -# source_encoding = 'utf-8' - -# The master toctree document. -master_doc = 'index' - # General information about the project. -project = 'pip' -copyright = '2008-2020, PyPA' - -# 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. - -version = release = 'dev' - -# Readthedocs seems to install pip as an egg (via setup.py install) which -# is somehow resulting in "import pip" picking up an older copy of pip. -# Rather than trying to force RTD to install pip properly, we'll simply -# read the version direct from the __init__.py file. (Yes, this is -# fragile, but it works...) - -pip_init = os.path.join(docs_dir, '..', 'src', 'pip', '__init__.py') -with open(pip_init) as f: +project = "pip" +copyright = "2008-2020, PyPA" + +# Find the version and release information. +# We have a single source of truth for our version number: pip's __init__.py file. +# This next bit of code reads from it. +file_with_version = os.path.join(docs_dir, "..", "src", "pip", "__init__.py") +with open(file_with_version) as f: for line in f: m = re.match(r'__version__ = "(.*)"', line) if m: __version__ = m.group(1) # The short X.Y version. - version = '.'.join(__version__.split('.')[:2]) + version = ".".join(__version__.split(".")[:2]) # The full version, including alpha/beta/rc tags. release = __version__ break + else: # AKA no-break + version = release = "dev" -# We have this here because readthedocs plays tricks sometimes and there seems -# to be a heisenbug, related to the version of pip discovered. This is here to -# help debug that if someone decides to do that in the future. print("pip version:", version) print("pip release:", release) -# 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 -# non-false value, then it is used: -# today = '' -# Else, today_fmt is used as the format for a strftime call. -today_fmt = '%B %d, %Y' - -# 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. -exclude_patterns = ['build/'] - -# The reST default role (used for this markup: `text`) to use for all documents -# default_role = None +# -- Options for smartquotes ---------------------------------------------------------- -# If true, '()' will be appended to :func: etc. cross-reference text. -# add_function_parentheses = True +# Disable the conversion of dashes so that long options like "--find-links" won't +# render as "-find-links" if included in the text.The default of "qDe" converts normal +# quote characters ('"' and "'"), en and em dashes ("--" and "---"), and ellipses "..." +smartquotes_action = "qe" -# If true, the current module name will be prepended to all description -# unit titles (such as .. function::). -# add_module_names = True +# -- Options for intersphinx ---------------------------------------------------------- -# If true, sectionauthor and moduleauthor directives will be shown in the -# output. They are ignored by default. -# show_authors = False +intersphinx_mapping = { + "python": ("https://docs.python.org/3", None), + "pypug": ("https://packaging.python.org", None), +} -# A list of ignored prefixes for module index sorting. -# modindex_common_prefix = [] +# -- Options for extlinks ------------------------------------------------------------- extlinks = { - 'issue': ('https://github.com/pypa/pip/issues/%s', '#'), - 'pull': ('https://github.com/pypa/pip/pull/%s', 'PR #'), - 'pypi': ('https://pypi.org/project/%s/', ''), + "issue": ("https://github.com/pypa/pip/issues/%s", "#"), + "pull": ("https://github.com/pypa/pip/pull/%s", "PR #"), + "pypi": ("https://pypi.org/project/%s/", ""), } -# Turn off sphinx build warnings because of sphinx tabs during man pages build -sphinx_tabs_nowarn = True - -# -- Options for HTML output -------------------------------------------------- +# -- Options for towncrier_draft extension -------------------------------------------- -# The theme to use for HTML and HTML Help pages. Major themes that come with -# Sphinx are currently 'default' and 'sphinxdoc'. -html_theme = "furo" - -# Theme options are theme-specific and customize the look and feel of a theme -# further. For a list of options available for each theme, see the -# documentation. -html_theme_options = {} +towncrier_draft_autoversion_mode = "draft" # or: 'sphinx-release', 'sphinx-version' +towncrier_draft_include_empty = True +towncrier_draft_working_directory = pathlib.Path(docs_dir).parent +# Not yet supported: towncrier_draft_config_path = 'pyproject.toml' # relative to cwd -# Add any paths that contain custom themes here, relative to this directory. +# -- Options for HTML ----------------------------------------------------------------- -# The name for this set of Sphinx documents. If None, it defaults to -# " v documentation". +html_theme = "furo" html_title = f"{project} documentation v{release}" -# 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. -# html_logo = '_static/piplogo.png' - -# 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 = 'favicon.png' - -# 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. -html_last_updated_fmt = '%b %d, %Y' - -# If true, the Docutils Smart Quotes transform (originally based on -# SmartyPants) will be used to convert characters like quotes and dashes -# to typographically correct entities. The default is True. -smartquotes = True - -# This string, for use with Docutils 0.14 or later, customizes the -# SmartQuotes transform. The default of "qDe" converts normal quote -# characters ('"' and "'"), en and em dashes ("--" and "---"), and -# ellipses "...". -# For now, we disable the conversion of dashes so that long options -# like "--find-links" won't render as "-find-links" if included in the -# text in places where monospaced type can't be used. For example, backticks -# can't be used inside roles like :ref:`--no-index <--no-index>` because -# of nesting. -smartquotes_action = "qe" - -# 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. -# html_additional_pages = {} - -# If false, no module index is generated. +# Disable the generation of the various indexes html_use_modindex = False - -# If false, no index is generated. html_use_index = False -# If true, the index is split into individual pages for each letter. -# html_split_index = False - -# If true, links to the reST sources are added to the pages. -html_show_sourcelink = False - -# If true, an OpenSearch description file will be output, and all pages will -# contain a 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"). -# html_file_suffix = '' - -# Output file base name for HTML help builder. -htmlhelp_basename = 'pipdocs' - - -# -- Options for LaTeX output ------------------------------------------------- - -# The paper size ('letter' or 'a4'). -# latex_paper_size = 'letter' - -# The font size ('10pt', '11pt' or '12pt'). -# latex_font_size = '10pt' - -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, author, documentclass [howto/manual]) -latex_documents = [ - ( - 'index', - 'pip.tex', - 'pip Documentation', - 'pip developers', - 'manual', - ), -] - -# 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, -# not chapters. -# latex_use_parts = False +# -- Options for Manual Pages --------------------------------------------------------- -# Additional stuff for the LaTeX preamble. -# latex_preamble = '' - -# Documents to append as an appendix to all manuals. -# latex_appendices = [] - -# If false, no module index is generated. -# latex_use_modindex = True - -# -- Options for Manual Pages ------------------------------------------------- # List of manual pages generated -man_pages = [ - ( - 'index', - 'pip', - 'package manager for Python packages', - 'pip developers', - 1 - ) -] - - -def to_document_name(path, base_dir): - """Convert a provided path to a Sphinx "document name". - """ - relative_path = os.path.relpath(path, base_dir) - root, _ = os.path.splitext(relative_path) - return root.replace(os.sep, '/') - - -# Here, we crawl the entire man/commands/ directory and list every file with -# appropriate name and details -man_dir = os.path.join(docs_dir, 'man') -raw_subcommands = glob.glob(os.path.join(man_dir, 'commands/*.rst')) -if not raw_subcommands: - raise FileNotFoundError( - 'The individual subcommand manpages could not be found!' - ) -for fname in raw_subcommands: - fname_base = to_document_name(fname, man_dir) - outname = 'pip-' + fname_base.split('/')[1] - description = 'description of {} command'.format( - outname.replace('-', ' ') - ) - - man_pages.append((fname_base, outname, description, 'pip developers', 1)) - -# -- Options for docs_feedback_sphinxext -------------------------------------- - -# NOTE: Must be one of 'attention', 'caution', 'danger', 'error', 'hint', -# NOTE: 'important', 'note', 'tip', 'warning' or 'admonition'. -docs_feedback_admonition_type = 'important' -docs_feedback_big_doc_lines = 50 # bigger docs will have a banner on top -docs_feedback_email = 'Docs UX Team ' -docs_feedback_excluded_documents = { # these won't have any banners - 'news', 'reference/index', -} -docs_feedback_questions_list = ( - 'What problem were you trying to solve when you came to this page?', - 'What content was useful?', - 'What content was not useful?', -) - -# -- Options for towncrier_draft extension ----------------------------------- - -towncrier_draft_autoversion_mode = 'draft' # or: 'sphinx-release', 'sphinx-version' -towncrier_draft_include_empty = False -towncrier_draft_working_directory = pathlib.Path(docs_dir).parent -# Not yet supported: towncrier_draft_config_path = 'pyproject.toml' # relative to cwd +def determine_man_pages(): + """Determine which man pages need to be generated.""" + + def to_document_name(path, base_dir): + """Convert a provided path to a Sphinx "document name".""" + relative_path = os.path.relpath(path, base_dir) + root, _ = os.path.splitext(relative_path) + return root.replace(os.sep, "/") + + # Crawl the entire man/commands/ directory and list every file with appropriate + # name and details. + man_dir = os.path.join(docs_dir, "man") + raw_subcommands = glob.glob(os.path.join(man_dir, "commands/*.rst")) + if not raw_subcommands: + raise FileNotFoundError( + "The individual subcommand manpages could not be found!" + ) + + retval = [ + ("index", "pip", "package manager for Python packages", "pip developers", 1), + ] + for fname in raw_subcommands: + fname_base = to_document_name(fname, man_dir) + outname = "pip-" + fname_base.split("/")[1] + description = "description of {} command".format(outname.replace("-", " ")) + + retval.append((fname_base, outname, description, "pip developers", 1)) + + return retval + + +man_pages = determine_man_pages() -- cgit v1.2.1