python-xmlsec/doc/source/conf.py at d450a30cd486dfc289fef5c921de2949d99f423d · xmlsec/python-xmlsec · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
from __future__ import annotations

import importlib.metadata
import urllib.request

import lxml
from docutils.nodes import Text, reference
from packaging.version import Version, parse
from sphinx.addnodes import pending_xref
from sphinx.application import Sphinx
from sphinx.environment import BuildEnvironment
from sphinx.errors import ExtensionError

extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode', 'sphinx.ext.intersphinx']

intersphinx_mapping = {'python': ('https://docs.python.org/3/', None)}

templates_path = ['_templates']
source_suffix = '.rst'
master_doc = 'index'

project = 'python-xmlsec'
copyright = '2020, Oleg Hoefling <oleg.hoefling@gmail.com>'
author = 'Bulat Gaifullin <gaifullinbf@gmail.com>'
release = importlib.metadata.version('xmlsec')
parsed: Version = parse(release)
version = f'{parsed.major}.{parsed.minor}'

exclude_patterns: list[str] = []
pygments_style = 'sphinx'
todo_include_todos = False

html_theme = 'furo'
html_static_path: list[str] = []
htmlhelp_basename = 'python-xmlsecdoc'

latex_elements: dict[str, str] = {}
latex_documents = [
    (
        master_doc,
        'python-xmlsec.tex',
        'python-xmlsec Documentation',
        'Bulat Gaifullin \\textless{}gaifullinbf@gmail.com\\textgreater{}',
        'manual',
    )
]

man_pages = [(master_doc, 'python-xmlsec', 'python-xmlsec Documentation', [author], 1)]

texinfo_documents = [
    (
        master_doc,
        'python-xmlsec',
        'python-xmlsec Documentation',
        author,
        'python-xmlsec',
        'One line description of project.',
        'Miscellaneous',
    )
]

autodoc_member_order = 'groupwise'
autodoc_docstring_signature = True


rst_prolog = """
.. role:: xml(code)
   :language: xml
"""

# LXML crossref'ing stuff:
# LXML doesn't have an intersphinx docs,
# so we link to lxml.etree._Element explicitly
lxml_element_cls_doc_uri = 'https://lxml.de/api/lxml.etree._Element-class.html'


def lxml_element_doc_reference(app: Sphinx, env: BuildEnvironment, node: pending_xref, contnode: Text) -> reference:
    """Handle a missing reference only if it is a ``lxml.etree._Element`` ref.

    We handle only :class:`lxml.etree._Element` and :class:`~lxml.etree._Element` nodes.
    """
    if (
        node.get('reftype', None) == 'class'
        and node.get('reftarget', None) == 'lxml.etree._Element'
        and contnode.astext() in ('lxml.etree._Element', '_Element')
    ):
        reftitle = f'(in lxml v{lxml.__version__})'  # type: ignore[attr-defined]
        newnode = reference('', '', internal=False, refuri=lxml_element_cls_doc_uri, reftitle=reftitle)
        newnode.append(contnode)
        return newnode


def setup(app: Sphinx) -> None:
    # first, check whether the doc URL is still valid
    if urllib.request.urlopen(lxml_element_cls_doc_uri).getcode() != 200:
        raise ExtensionError('URL to `lxml.etree._Element` docs is not accesible.')
    app.connect('missing-reference', lxml_element_doc_reference)