patroni/docs/conf.py

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
#
# Patroni documentation build configuration file, created by
# sphinx-quickstart on Mon Dec 19 16:54:09 2016.
#
# 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.

# 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.
#
import os

import sys

from sphinx.application import ENV_PICKLE_FILENAME

sys.path.insert(0, os.path.abspath('..'))

from patroni.version import __version__

project_root = os.path.abspath(os.path.join(os.path.dirname(__file__), '..'))
module_dir = os.path.abspath(os.path.join(project_root, 'patroni'))
excludes = ['tests', 'setup.py', 'conf']

# -- General configuration ------------------------------------------------

# If your documentation needs a minimal Sphinx version, state it here.
#
# needs_sphinx = '1.0'

# 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.intersphinx',
    'sphinx.ext.todo',
    'sphinx.ext.mathjax',
    'sphinx.ext.ifconfig',
    # 'sphinx.ext.viewcode',
    'sphinx_github_style',  # Generate "View on GitHub" for source code
    'sphinxcontrib.apidoc',  # For generating module docs from code
    'sphinx.ext.autodoc',  # For generating module docs from docstrings
    'sphinx.ext.napoleon',  # For Google and Numpy formatted docstrings
]
apidoc_module_dir = module_dir
apidoc_output_dir = 'modules'
apidoc_excluded_paths = excludes
apidoc_separate_modules = True

# Include autodoc for all members, including private ones and the ones that are missing a docstring.
autodoc_default_options = {
    "members": True,
    "undoc-members": True,
    "private-members": True,
}

# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']

# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
#
# source_suffix = ['.rst', '.md']
source_suffix = '.rst'

# The master toctree document.
master_doc = 'index'

# General information about the project.
project = 'Patroni'
copyright = '2024 Compose, Zalando SE, Patroni Contributors'
author = 'Patroni Contributors'

# 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 = __version__[:__version__.rfind('.')]
# 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.
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = 'en'

# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This patterns also effect to html_static_path and html_extra_path
exclude_patterns = []

# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'

# If true, `todo` and `todoList` produce output, else they produce nothing.
todo_include_todos = True


# -- Options for HTML output ----------------------------------------------

# The theme to use for HTML and HTML Help pages.  See the documentation for
# a list of builtin themes.
#

html_theme = 'sphinx_rtd_theme'
on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
if not on_rtd:  # only import and set the theme if we're building docs locally
    import sphinx_rtd_theme
    html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]

# 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 = {}

# 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 = ['_static']

# Replace "source" links with "edit on GitHub" when using rtd theme
html_context = {
    'display_github': True,
    'github_user': 'patroni',
    'github_repo': 'patroni',
    'github_version': 'master',
    'conf_py_path': '/docs/',
}

# sphinx-github-style options, https://sphinx-github-style.readthedocs.io/en/latest/index.html

# The name of the top-level package.
top_level = "patroni"

# The blob to link to on GitHub - any of "head", "last_tag", or "{blob}"
# linkcode_blob = 'head'

# The link to your GitHub repository formatted as https://github.com/user/repo
# If not provided, will attempt to create the link from the html_context dict
# linkcode_url = f"https://github.com/{html_context['github_user']}/" \
#                f"{html_context['github_repo']}/{html_context['github_version']}"

# The text to use for the linkcode link
# linkcode_link_text: str = "View on GitHub"

# A linkcode_resolve() function to use for resolving the link target
# linkcode_resolve: types.FunctionType


# -- Options for HTMLHelp output ------------------------------------------

# Output file base name for HTML help builder.
htmlhelp_basename = 'Patronidoc'


# -- Options for LaTeX output ---------------------------------------------

latex_elements = {
    # The paper size ('letterpaper' or 'a4paper').
    #
    # 'papersize': 'letterpaper',

    # The font size ('10pt', '11pt' or '12pt').
    #
    # 'pointsize': '10pt',

    # Additional stuff for the LaTeX preamble.
    #
    # 'preamble': '',

    # Latex figure (float) alignment
    #
    # 'figure_align': 'htbp',
}

# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
#  author, documentclass [howto, manual, or own class]).
latex_documents = [
    (master_doc, 'Patroni.tex', 'Patroni Documentation',
     'Patroni Contributors', 'manual'),
]


# -- Options for manual page output ---------------------------------------

# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
    (master_doc, 'patroni', 'Patroni Documentation',
     [author], 1)
]


# -- Options for Texinfo output -------------------------------------------

# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
#  dir menu entry, description, category)
texinfo_documents = [
    (master_doc, 'Patroni', 'Patroni Documentation',
     author, 'Patroni', 'One line description of project.',
     'Miscellaneous'),
]


# -- Options for Epub output ----------------------------------------------

# Bibliographic Dublin Core info.
epub_title = project
epub_author = author
epub_publisher = author
epub_copyright = copyright

# The unique identifier of the text. This can be a ISBN number
# or the project homepage.
#
# epub_identifier = ''

# A unique identification for the text.
#
# epub_uid = ''

# A list of files that should not be packed into the epub file.
epub_exclude_files = ['search.html']


# Example configuration for intersphinx: refer to the Python standard library.
intersphinx_mapping = {'python': ('https://docs.python.org/', None)}


# Remove these pages from index, references, toc trees, etc.
# If the builder is not 'html' then add the API docs modules index to pages to be removed.
exclude_from_builder = {
    'latex': ['modules/'],
    'epub': ['modules/'],
}
# Internal holding list, anything added here will always be excluded
_docs_to_remove = []


def config_inited(app, config):
    """Run during Sphinx `config-inited` phase.

    rtd reuses the environment, and there is no way to customize this behavior.
    Thus we remove the saved env.
    """
    pickle_file = os.path.join(app.doctreedir, ENV_PICKLE_FILENAME)
    if on_rtd and os.path.exists(pickle_file):
        os.remove(pickle_file)


def builder_inited(app):
    """Run during Sphinx `builder-inited` phase.

    Set a config value to builder name and add module docs to `docs_to_remove`.
    """
    print(f'The builder is: {app.builder.name}')
    app.add_config_value('builder', app.builder.name, 'env')

    # Remove pages when builder matches any referenced in exclude_from_builder
    if exclude_from_builder.get(app.builder.name):
        _docs_to_remove.extend(exclude_from_builder[app.builder.name])


def _to_be_removed(doc):
    for remove in _docs_to_remove:
        if doc.startswith(remove):
            return True
    return False


def env_get_outdated(app, env, added, changed, removed):
    """Run during Sphinx `env-get-outdated` phase.

    Remove the items listed in `docs_to_remove` from known pages.
    """
    to_remove = set()
    for doc in env.found_docs:
        if _to_be_removed(doc):
            to_remove.add(doc)
    added.difference_update(to_remove)
    changed.difference_update(to_remove)
    removed.update(to_remove)
    env.project.docnames.difference_update(to_remove)
    return []


def doctree_read(app, doctree):
    """Run during Sphinx `doctree-read` phase.

    Remove the items listed in `docs_to_remove` from the table of contents.
    """
    from sphinx import addnodes
    for toc_tree_node in doctree.traverse(addnodes.toctree):
        for e in toc_tree_node['entries']:
            if _to_be_removed(str(e[1])):
                toc_tree_node['entries'].remove(e)


def autodoc_skip(app, what, name, obj, would_skip, options):
    """Include autodoc of ``__init__`` methods, which are skipped by default."""
    if name == "__init__":
        return False
    return would_skip



# A possibility to have an own stylesheet, to add new rules or override existing ones
# For the latter case, the CSS specificity of the rules should be higher than the default ones
def setup(app):
    if hasattr(app, 'add_css_file'):
        app.add_css_file('custom.css')
    else:
        app.add_stylesheet('custom.css')

    # Run extra steps to remove module docs when running with a non-html builder
    app.connect('config-inited', config_inited)
    app.connect('builder-inited', builder_inited)
    app.connect('env-get-outdated', env_get_outdated)
    app.connect('doctree-read', doctree_read)
    app.connect("autodoc-skip-member", autodoc_skip)