Mercurial > hgrepos > Python > libs > pygments-lexer-pseudocode2

annotate docs/conf.py @ 193:af8eca1e9006

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
FIX: Typo in "recognize"
author Franz Glasner <fzglas.hg@dom66.de>
date Wed, 13 May 2026 11:38:32 +0200
parents c10b2092c48f
children d57cf1bb96d6
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
45
6ac1ea5d2d4a Begin documentation: add the Sphinx generated configuration as-is
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
1 # Configuration file for the Sphinx documentation builder.
6ac1ea5d2d4a Begin documentation: add the Sphinx generated configuration as-is
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
2 #
6ac1ea5d2d4a Begin documentation: add the Sphinx generated configuration as-is
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
3 # For the full list of built-in configuration values, see the documentation:
6ac1ea5d2d4a Begin documentation: add the Sphinx generated configuration as-is
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
4 # https://www.sphinx-doc.org/en/master/usage/configuration.html
6ac1ea5d2d4a Begin documentation: add the Sphinx generated configuration as-is
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
5
49
5c0f26a21e81 Determine "release" dynamically from the package's "__version__"
Franz Glasner <fzglas.hg@dom66.de>
parents: 48
diff changeset
6 import ast
167
ddefcc20367c More static and/or dynamic metadata into README and project's init: release date, revision.
Franz Glasner <fzglas.hg@dom66.de>
parents: 166
diff changeset
7 import datetime
63
414bf3cbb152 Add a custom lexer to the Sphinx application dynamically with "no_end" set to True
Franz Glasner <fzglas.hg@dom66.de>
parents: 60
diff changeset
8 import functools
49
5c0f26a21e81 Determine "release" dynamically from the package's "__version__"
Franz Glasner <fzglas.hg@dom66.de>
parents: 48
diff changeset
9 import io
63
414bf3cbb152 Add a custom lexer to the Sphinx application dynamically with "no_end" set to True
Franz Glasner <fzglas.hg@dom66.de>
parents: 60
diff changeset
10 import os
414bf3cbb152 Add a custom lexer to the Sphinx application dynamically with "no_end" set to True
Franz Glasner <fzglas.hg@dom66.de>
parents: 60
diff changeset
11 import sys
49
5c0f26a21e81 Determine "release" dynamically from the package's "__version__"
Franz Glasner <fzglas.hg@dom66.de>
parents: 48
diff changeset
12 import re
5c0f26a21e81 Determine "release" dynamically from the package's "__version__"
Franz Glasner <fzglas.hg@dom66.de>
parents: 48
diff changeset
13
185
b27557f6d393 Allow to build the documentation when the project is not installed
Franz Glasner <fzglas.hg@dom66.de>
parents: 183
diff changeset
14 import pygments.lexers
b27557f6d393 Allow to build the documentation when the project is not installed
Franz Glasner <fzglas.hg@dom66.de>
parents: 183
diff changeset
15 import pygments.filters
b27557f6d393 Allow to build the documentation when the project is not installed
Franz Glasner <fzglas.hg@dom66.de>
parents: 183
diff changeset
16 import sphinx.util.logging
b27557f6d393 Allow to build the documentation when the project is not installed
Franz Glasner <fzglas.hg@dom66.de>
parents: 183
diff changeset
17
63
414bf3cbb152 Add a custom lexer to the Sphinx application dynamically with "no_end" set to True
Franz Glasner <fzglas.hg@dom66.de>
parents: 60
diff changeset
18 sys.path.insert(0, os.path.dirname(os.path.abspath('.')))
414bf3cbb152 Add a custom lexer to the Sphinx application dynamically with "no_end" set to True
Franz Glasner <fzglas.hg@dom66.de>
parents: 60
diff changeset
19
185
b27557f6d393 Allow to build the documentation when the project is not installed
Franz Glasner <fzglas.hg@dom66.de>
parents: 183
diff changeset
20 from pygments_lexer_pseudocode2.lexers.algpseudocode import (
b27557f6d393 Allow to build the documentation when the project is not installed
Franz Glasner <fzglas.hg@dom66.de>
parents: 183
diff changeset
21 AlgPseudocodeLexer, AlgPseudocodeLexer_DE, AlgPseudocodeLexer_FR)
b27557f6d393 Allow to build the documentation when the project is not installed
Franz Glasner <fzglas.hg@dom66.de>
parents: 183
diff changeset
22 from pygments_lexer_pseudocode2.lexers.fr_pseudocode import FrPseudocodeLexer
b27557f6d393 Allow to build the documentation when the project is not installed
Franz Glasner <fzglas.hg@dom66.de>
parents: 183
diff changeset
23 from pygments_lexer_pseudocode2.filters import (
b27557f6d393 Allow to build the documentation when the project is not installed
Franz Glasner <fzglas.hg@dom66.de>
parents: 183
diff changeset
24 TokenReplaceFilter, ErrorToGenericErrorTokenFilter)
68
93ade4c595b7 Reorg conf.py: import globally
Franz Glasner <fzglas.hg@dom66.de>
parents: 63
diff changeset
25
93ade4c595b7 Reorg conf.py: import globally
Franz Glasner <fzglas.hg@dom66.de>
parents: 63
diff changeset
26
134
62407bd73ba8 Require Sphinx >= 2.1.
Franz Glasner <fzglas.hg@dom66.de>
parents: 132
diff changeset
27 needs_sphinx = '2.1'
183
e3523930294a More comments on the needed Sphinx version
Franz Glasner <fzglas.hg@dom66.de>
parents: 182
diff changeset
28 """This is the theory:
e3523930294a More comments on the needed Sphinx version
Franz Glasner <fzglas.hg@dom66.de>
parents: 182
diff changeset
29
e3523930294a More comments on the needed Sphinx version
Franz Glasner <fzglas.hg@dom66.de>
parents: 182
diff changeset
30 - 2.1: - :py:meth:Sphinx.add_lexer` takes a class as argument
e3523930294a More comments on the needed Sphinx version
Franz Glasner <fzglas.hg@dom66.de>
parents: 182
diff changeset
31
e3523930294a More comments on the needed Sphinx version
Franz Glasner <fzglas.hg@dom66.de>
parents: 182
diff changeset
32 Currently really built and tested with Sphinx 7.1.2.
155
16faae7ecdb6 Document why Sphinx>=2.1 is needed
Franz Glasner <fzglas.hg@dom66.de>
parents: 151
diff changeset
33
16faae7ecdb6 Document why Sphinx>=2.1 is needed
Franz Glasner <fzglas.hg@dom66.de>
parents: 151
diff changeset
34 """
134
62407bd73ba8 Require Sphinx >= 2.1.
Franz Glasner <fzglas.hg@dom66.de>
parents: 132
diff changeset
35
167
ddefcc20367c More static and/or dynamic metadata into README and project's init: release date, revision.
Franz Glasner <fzglas.hg@dom66.de>
parents: 166
diff changeset
36 today = datetime.date.today().isoformat()
134
62407bd73ba8 Require Sphinx >= 2.1.
Franz Glasner <fzglas.hg@dom66.de>
parents: 132
diff changeset
37
171
4b87a9ecffdd The first somewhat useable version of documentation in PDF.
Franz Glasner <fzglas.hg@dom66.de>
parents: 170
diff changeset
38 master_doc = "index"
4b87a9ecffdd The first somewhat useable version of documentation in PDF.
Franz Glasner <fzglas.hg@dom66.de>
parents: 170
diff changeset
39
45
6ac1ea5d2d4a Begin documentation: add the Sphinx generated configuration as-is
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
40 # -- Project information -----------------------------------------------------
6ac1ea5d2d4a Begin documentation: add the Sphinx generated configuration as-is
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
41 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
6ac1ea5d2d4a Begin documentation: add the Sphinx generated configuration as-is
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
42
6ac1ea5d2d4a Begin documentation: add the Sphinx generated configuration as-is
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
43 project = 'Pygments Pseudocode Lexer'
167
ddefcc20367c More static and/or dynamic metadata into README and project's init: release date, revision.
Franz Glasner <fzglas.hg@dom66.de>
parents: 166
diff changeset
44 copyright = u'2026 Franz Glasner. © Copyright 2015 Simon Wachter'
45
6ac1ea5d2d4a Begin documentation: add the Sphinx generated configuration as-is
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
45 author = 'Franz Glasner'
167
ddefcc20367c More static and/or dynamic metadata into README and project's init: release date, revision.
Franz Glasner <fzglas.hg@dom66.de>
parents: 166
diff changeset
46 #
ddefcc20367c More static and/or dynamic metadata into README and project's init: release date, revision.
Franz Glasner <fzglas.hg@dom66.de>
parents: 166
diff changeset
47 # Determine "release" and other release metadata dynamically from the
ddefcc20367c More static and/or dynamic metadata into README and project's init: release date, revision.
Franz Glasner <fzglas.hg@dom66.de>
parents: 166
diff changeset
48 # package's "__version__" or other VCS data.
ddefcc20367c More static and/or dynamic metadata into README and project's init: release date, revision.
Franz Glasner <fzglas.hg@dom66.de>
parents: 166
diff changeset
49 #
49
5c0f26a21e81 Determine "release" dynamically from the package's "__version__"
Franz Glasner <fzglas.hg@dom66.de>
parents: 48
diff changeset
50 with io.open("../pygments_lexer_pseudocode2/__init__.py",
5c0f26a21e81 Determine "release" dynamically from the package's "__version__"
Franz Glasner <fzglas.hg@dom66.de>
parents: 48
diff changeset
51 "rt",
5c0f26a21e81 Determine "release" dynamically from the package's "__version__"
Franz Glasner <fzglas.hg@dom66.de>
parents: 48
diff changeset
52 encoding="utf-8") as relfp:
167
ddefcc20367c More static and/or dynamic metadata into README and project's init: release date, revision.
Franz Glasner <fzglas.hg@dom66.de>
parents: 166
diff changeset
53 verfiledata = relfp.read()
49
5c0f26a21e81 Determine "release" dynamically from the package's "__version__"
Franz Glasner <fzglas.hg@dom66.de>
parents: 48
diff changeset
54 release = ast.literal_eval(
5c0f26a21e81 Determine "release" dynamically from the package's "__version__"
Franz Glasner <fzglas.hg@dom66.de>
parents: 48
diff changeset
55 re.search(r"""^\s*__version__\s*=\s*(("|')[^"']*\2)""",
167
ddefcc20367c More static and/or dynamic metadata into README and project's init: release date, revision.
Franz Glasner <fzglas.hg@dom66.de>
parents: 166
diff changeset
56 verfiledata,
ddefcc20367c More static and/or dynamic metadata into README and project's init: release date, revision.
Franz Glasner <fzglas.hg@dom66.de>
parents: 166
diff changeset
57 re.MULTILINE).group(1))
ddefcc20367c More static and/or dynamic metadata into README and project's init: release date, revision.
Franz Glasner <fzglas.hg@dom66.de>
parents: 166
diff changeset
58 release_date = (
ddefcc20367c More static and/or dynamic metadata into README and project's init: release date, revision.
Franz Glasner <fzglas.hg@dom66.de>
parents: 166
diff changeset
59 ast.literal_eval(
ddefcc20367c More static and/or dynamic metadata into README and project's init: release date, revision.
Franz Glasner <fzglas.hg@dom66.de>
parents: 166
diff changeset
60 re.search(r"""^\s*__date__\s*=\s*(("|')[^"']*\2)""",
ddefcc20367c More static and/or dynamic metadata into README and project's init: release date, revision.
Franz Glasner <fzglas.hg@dom66.de>
parents: 166
diff changeset
61 verfiledata,
ddefcc20367c More static and/or dynamic metadata into README and project's init: release date, revision.
Franz Glasner <fzglas.hg@dom66.de>
parents: 166
diff changeset
62 re.MULTILINE).group(1))
ddefcc20367c More static and/or dynamic metadata into README and project's init: release date, revision.
Franz Glasner <fzglas.hg@dom66.de>
parents: 166
diff changeset
63 or "dev:%s" % (today,)
ddefcc20367c More static and/or dynamic metadata into README and project's init: release date, revision.
Franz Glasner <fzglas.hg@dom66.de>
parents: 166
diff changeset
64 )
ddefcc20367c More static and/or dynamic metadata into README and project's init: release date, revision.
Franz Glasner <fzglas.hg@dom66.de>
parents: 166
diff changeset
65 release_rev = ast.literal_eval(
ddefcc20367c More static and/or dynamic metadata into README and project's init: release date, revision.
Franz Glasner <fzglas.hg@dom66.de>
parents: 166
diff changeset
66 re.search(r"""^\s*__revision__\s*=\s*(("|')[^"']*\2)""",
ddefcc20367c More static and/or dynamic metadata into README and project's init: release date, revision.
Franz Glasner <fzglas.hg@dom66.de>
parents: 166
diff changeset
67 verfiledata,
ddefcc20367c More static and/or dynamic metadata into README and project's init: release date, revision.
Franz Glasner <fzglas.hg@dom66.de>
parents: 166
diff changeset
68 re.MULTILINE).group(1))
ddefcc20367c More static and/or dynamic metadata into README and project's init: release date, revision.
Franz Glasner <fzglas.hg@dom66.de>
parents: 166
diff changeset
69 if release_rev.startswith("|") or release_rev.endswith("|"):
ddefcc20367c More static and/or dynamic metadata into README and project's init: release date, revision.
Franz Glasner <fzglas.hg@dom66.de>
parents: 166
diff changeset
70 # Assume that make export (hg kwarchive) is not called.
ddefcc20367c More static and/or dynamic metadata into README and project's init: release date, revision.
Franz Glasner <fzglas.hg@dom66.de>
parents: 166
diff changeset
71 import subprocess
ddefcc20367c More static and/or dynamic metadata into README and project's init: release date, revision.
Franz Glasner <fzglas.hg@dom66.de>
parents: 166
diff changeset
72 try:
ddefcc20367c More static and/or dynamic metadata into README and project's init: release date, revision.
Franz Glasner <fzglas.hg@dom66.de>
parents: 166
diff changeset
73 release_rev = subprocess.check_output(
ddefcc20367c More static and/or dynamic metadata into README and project's init: release date, revision.
Franz Glasner <fzglas.hg@dom66.de>
parents: 166
diff changeset
74 ["hg", "id", "-i"], stderr=subprocess.STDOUT)
ddefcc20367c More static and/or dynamic metadata into README and project's init: release date, revision.
Franz Glasner <fzglas.hg@dom66.de>
parents: 166
diff changeset
75 except Exception:
ddefcc20367c More static and/or dynamic metadata into README and project's init: release date, revision.
Franz Glasner <fzglas.hg@dom66.de>
parents: 166
diff changeset
76 release_rev = "<unknown>"
ddefcc20367c More static and/or dynamic metadata into README and project's init: release date, revision.
Franz Glasner <fzglas.hg@dom66.de>
parents: 166
diff changeset
77 else:
ddefcc20367c More static and/or dynamic metadata into README and project's init: release date, revision.
Franz Glasner <fzglas.hg@dom66.de>
parents: 166
diff changeset
78 if sys.version_info[0] >= 3:
ddefcc20367c More static and/or dynamic metadata into README and project's init: release date, revision.
Franz Glasner <fzglas.hg@dom66.de>
parents: 166
diff changeset
79 release_rev = release_rev.decode("ascii")
ddefcc20367c More static and/or dynamic metadata into README and project's init: release date, revision.
Franz Glasner <fzglas.hg@dom66.de>
parents: 166
diff changeset
80 release_rev = "dev:%s" % (release_rev.strip(),)
ddefcc20367c More static and/or dynamic metadata into README and project's init: release date, revision.
Franz Glasner <fzglas.hg@dom66.de>
parents: 166
diff changeset
81 define_rest_keywords = True
ddefcc20367c More static and/or dynamic metadata into README and project's init: release date, revision.
Franz Glasner <fzglas.hg@dom66.de>
parents: 166
diff changeset
82 else:
ddefcc20367c More static and/or dynamic metadata into README and project's init: release date, revision.
Franz Glasner <fzglas.hg@dom66.de>
parents: 166
diff changeset
83 #
ddefcc20367c More static and/or dynamic metadata into README and project's init: release date, revision.
Franz Glasner <fzglas.hg@dom66.de>
parents: 166
diff changeset
84 # Assume that all keywords are expanded properly everywhere:
ddefcc20367c More static and/or dynamic metadata into README and project's init: release date, revision.
Franz Glasner <fzglas.hg@dom66.de>
parents: 166
diff changeset
85 # do not define special VCSxxx keyword below.
ddefcc20367c More static and/or dynamic metadata into README and project's init: release date, revision.
Franz Glasner <fzglas.hg@dom66.de>
parents: 166
diff changeset
86 #
ddefcc20367c More static and/or dynamic metadata into README and project's init: release date, revision.
Franz Glasner <fzglas.hg@dom66.de>
parents: 166
diff changeset
87 define_rest_keywords = False
ddefcc20367c More static and/or dynamic metadata into README and project's init: release date, revision.
Franz Glasner <fzglas.hg@dom66.de>
parents: 166
diff changeset
88
51
b4c255f8bdc4 Also define "version" (identical to "release" yet)
Franz Glasner <fzglas.hg@dom66.de>
parents: 50
diff changeset
89 version = release
157
902147c24f9b Disable a default domain when generating the docs
Franz Glasner <fzglas.hg@dom66.de>
parents: 155
diff changeset
90 primary_domain = None
60
0ff291eac663 Minimal Sphinx configuration for the first tests
Franz Glasner <fzglas.hg@dom66.de>
parents: 51
diff changeset
91
45
6ac1ea5d2d4a Begin documentation: add the Sphinx generated configuration as-is
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
92 # -- General configuration ---------------------------------------------------
6ac1ea5d2d4a Begin documentation: add the Sphinx generated configuration as-is
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
93 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
6ac1ea5d2d4a Begin documentation: add the Sphinx generated configuration as-is
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
94
60
0ff291eac663 Minimal Sphinx configuration for the first tests
Franz Glasner <fzglas.hg@dom66.de>
parents: 51
diff changeset
95 extensions = [
0ff291eac663 Minimal Sphinx configuration for the first tests
Franz Glasner <fzglas.hg@dom66.de>
parents: 51
diff changeset
96 "sphinx.ext.todo",
0ff291eac663 Minimal Sphinx configuration for the first tests
Franz Glasner <fzglas.hg@dom66.de>
parents: 51
diff changeset
97 ]
45
6ac1ea5d2d4a Begin documentation: add the Sphinx generated configuration as-is
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
98
6ac1ea5d2d4a Begin documentation: add the Sphinx generated configuration as-is
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
99 templates_path = ['_templates']
141
acd9073cbbe3 Make a lexerlist.rst that contains the table of the lexers because it is used at least twice
Franz Glasner <fzglas.hg@dom66.de>
parents: 139
diff changeset
100 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'lexerlist.rst']
45
6ac1ea5d2d4a Begin documentation: add the Sphinx generated configuration as-is
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
101
132
a3e765f1ad23 Explicitely set "highlight_languge" to "none" in the docs configuration.
Franz Glasner <fzglas.hg@dom66.de>
parents: 121
diff changeset
102 highlight_language = "none"
a3e765f1ad23 Explicitely set "highlight_languge" to "none" in the docs configuration.
Franz Glasner <fzglas.hg@dom66.de>
parents: 121
diff changeset
103
145
c4f6f5e771b0 Also define the :algpseudocode: role globally in the package documentation.
Franz Glasner <fzglas.hg@dom66.de>
parents: 144
diff changeset
104 rst_prolog = """
c4f6f5e771b0 Also define the :algpseudocode: role globally in the package documentation.
Franz Glasner <fzglas.hg@dom66.de>
parents: 144
diff changeset
105 .. role:: algpseudocode(code)
167
ddefcc20367c More static and/or dynamic metadata into README and project's init: release date, revision.
Franz Glasner <fzglas.hg@dom66.de>
parents: 166
diff changeset
106 .. |release_date| replace:: %s
ddefcc20367c More static and/or dynamic metadata into README and project's init: release date, revision.
Franz Glasner <fzglas.hg@dom66.de>
parents: 166
diff changeset
107 .. |release_rev| replace:: %s
ddefcc20367c More static and/or dynamic metadata into README and project's init: release date, revision.
Franz Glasner <fzglas.hg@dom66.de>
parents: 166
diff changeset
108 """ % (release_date, release_rev)
ddefcc20367c More static and/or dynamic metadata into README and project's init: release date, revision.
Franz Glasner <fzglas.hg@dom66.de>
parents: 166
diff changeset
109 if define_rest_keywords:
ddefcc20367c More static and/or dynamic metadata into README and project's init: release date, revision.
Franz Glasner <fzglas.hg@dom66.de>
parents: 166
diff changeset
110 rst_prolog += """\
ddefcc20367c More static and/or dynamic metadata into README and project's init: release date, revision.
Franz Glasner <fzglas.hg@dom66.de>
parents: 166
diff changeset
111 .. |VCSJustDate| replace:: %s
ddefcc20367c More static and/or dynamic metadata into README and project's init: release date, revision.
Franz Glasner <fzglas.hg@dom66.de>
parents: 166
diff changeset
112 .. |VCSRevision| replace:: %s
ddefcc20367c More static and/or dynamic metadata into README and project's init: release date, revision.
Franz Glasner <fzglas.hg@dom66.de>
parents: 166
diff changeset
113 """ % (release_date, release_rev)
144
b616f9645e37 More referencing with internal and external links
Franz Glasner <fzglas.hg@dom66.de>
parents: 143
diff changeset
114 rst_epilog = """
145
c4f6f5e771b0 Also define the :algpseudocode: role globally in the package documentation.
Franz Glasner <fzglas.hg@dom66.de>
parents: 144
diff changeset
115 .. _Pygments: https://pygments.org/
144
b616f9645e37 More referencing with internal and external links
Franz Glasner <fzglas.hg@dom66.de>
parents: 143
diff changeset
116 .. _Sphinx: https://www.sphinx-doc.org
145
c4f6f5e771b0 Also define the :algpseudocode: role globally in the package documentation.
Franz Glasner <fzglas.hg@dom66.de>
parents: 144
diff changeset
117 .. _Python: https://www.python.org/
150
4acf578ae93f Much more details in the documentation
Franz Glasner <fzglas.hg@dom66.de>
parents: 145
diff changeset
118 .. _Algpseudocodex: https://ctan.org/pkg/algpseudocodex
144
b616f9645e37 More referencing with internal and external links
Franz Glasner <fzglas.hg@dom66.de>
parents: 143
diff changeset
119 """
b616f9645e37 More referencing with internal and external links
Franz Glasner <fzglas.hg@dom66.de>
parents: 143
diff changeset
120
60
0ff291eac663 Minimal Sphinx configuration for the first tests
Franz Glasner <fzglas.hg@dom66.de>
parents: 51
diff changeset
121
0ff291eac663 Minimal Sphinx configuration for the first tests
Franz Glasner <fzglas.hg@dom66.de>
parents: 51
diff changeset
122 # --- Options for todo extension ---------------------------------------------
0ff291eac663 Minimal Sphinx configuration for the first tests
Franz Glasner <fzglas.hg@dom66.de>
parents: 51
diff changeset
123 todo_include_todos = True
45
6ac1ea5d2d4a Begin documentation: add the Sphinx generated configuration as-is
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
124
6ac1ea5d2d4a Begin documentation: add the Sphinx generated configuration as-is
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
125
6ac1ea5d2d4a Begin documentation: add the Sphinx generated configuration as-is
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
126 # -- Options for HTML output -------------------------------------------------
6ac1ea5d2d4a Begin documentation: add the Sphinx generated configuration as-is
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
127 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
6ac1ea5d2d4a Begin documentation: add the Sphinx generated configuration as-is
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
128
139
d8ac51cba0ff Customize the HTML title for the haiku theme
Franz Glasner <fzglas.hg@dom66.de>
parents: 135
diff changeset
129 html_static_path = ['_static']
186
95754197f5b3 Link to some source code of example pseudocode files
Franz Glasner <fzglas.hg@dom66.de>
parents: 185
diff changeset
130 html_extra_path = ['../LICENSES']
167
ddefcc20367c More static and/or dynamic metadata into README and project's init: release date, revision.
Franz Glasner <fzglas.hg@dom66.de>
parents: 166
diff changeset
131 html_copy_source = False
ddefcc20367c More static and/or dynamic metadata into README and project's init: release date, revision.
Franz Glasner <fzglas.hg@dom66.de>
parents: 166
diff changeset
132 html_show_sourcelink = False
139
d8ac51cba0ff Customize the HTML title for the haiku theme
Franz Glasner <fzglas.hg@dom66.de>
parents: 135
diff changeset
133
121
a3ed7d8231d7 Comment
Franz Glasner <fzglas.hg@dom66.de>
parents: 119
diff changeset
134 #html_theme = 'alabaster'
60
0ff291eac663 Minimal Sphinx configuration for the first tests
Franz Glasner <fzglas.hg@dom66.de>
parents: 51
diff changeset
135 html_theme = 'haiku'
170
f761694373e0 Do not justify the documentation output.
Franz Glasner <fzglas.hg@dom66.de>
parents: 167
diff changeset
136 html_css_files = ["custom-haiku.css"]
139
d8ac51cba0ff Customize the HTML title for the haiku theme
Franz Glasner <fzglas.hg@dom66.de>
parents: 135
diff changeset
137 html_title = 'The %s v%s' % (project, release)
d8ac51cba0ff Customize the HTML title for the haiku theme
Franz Glasner <fzglas.hg@dom66.de>
parents: 135
diff changeset
138 html_short_title = html_title
167
ddefcc20367c More static and/or dynamic metadata into README and project's init: release date, revision.
Franz Glasner <fzglas.hg@dom66.de>
parents: 166
diff changeset
139 html_last_updated_fmt = "%s (rv:%s)" % (today, release_rev)
143
6da3b9dd4294 FIX: Do not use the default pygments style "sphinx"; was submitted erroneously
Franz Glasner <fzglas.hg@dom66.de>
parents: 141
diff changeset
140 #pygments_style = "sphinx"
6da3b9dd4294 FIX: Do not use the default pygments style "sphinx"; was submitted erroneously
Franz Glasner <fzglas.hg@dom66.de>
parents: 141
diff changeset
141 pygments_style = "default"
63
414bf3cbb152 Add a custom lexer to the Sphinx application dynamically with "no_end" set to True
Franz Glasner <fzglas.hg@dom66.de>
parents: 60
diff changeset
142
171
4b87a9ecffdd The first somewhat useable version of documentation in PDF.
Franz Glasner <fzglas.hg@dom66.de>
parents: 170
diff changeset
143 # --- Options for LaTeX output -----------------------------------------------
4b87a9ecffdd The first somewhat useable version of documentation in PDF.
Franz Glasner <fzglas.hg@dom66.de>
parents: 170
diff changeset
144 # https://www.sphinx-doc.org/en/master/latex.html
4b87a9ecffdd The first somewhat useable version of documentation in PDF.
Franz Glasner <fzglas.hg@dom66.de>
parents: 170
diff changeset
145 latex_engine = 'lualatex'
4b87a9ecffdd The first somewhat useable version of documentation in PDF.
Franz Glasner <fzglas.hg@dom66.de>
parents: 170
diff changeset
146 latex_elements = {
4b87a9ecffdd The first somewhat useable version of documentation in PDF.
Franz Glasner <fzglas.hg@dom66.de>
parents: 170
diff changeset
147 "papersize": "a4paper",
4b87a9ecffdd The first somewhat useable version of documentation in PDF.
Franz Glasner <fzglas.hg@dom66.de>
parents: 170
diff changeset
148 "babel": r"\usepackage{babel}",
181
dcbc66f851eb A style file for (Lua)LaTeX that loads the required fonts.
Franz Glasner <fzglas.hg@dom66.de>
parents: 176
diff changeset
149 "fontpkg": r"\usepackage[plexmono]{my-doc-fonts}",
191
c10b2092c48f Also make a PDF style variant using Adobe Source Serif/Sans/Code Pro
Franz Glasner <fzglas.hg@dom66.de>
parents: 188
diff changeset
150 # "fontpkg": r"\usepackage[adobesource]{my-doc-fonts}",
171
4b87a9ecffdd The first somewhat useable version of documentation in PDF.
Franz Glasner <fzglas.hg@dom66.de>
parents: 170
diff changeset
151 "releasename": "Version",
4b87a9ecffdd The first somewhat useable version of documentation in PDF.
Franz Glasner <fzglas.hg@dom66.de>
parents: 170
diff changeset
152 }
4b87a9ecffdd The first somewhat useable version of documentation in PDF.
Franz Glasner <fzglas.hg@dom66.de>
parents: 170
diff changeset
153 latex_theme = "manual"
4b87a9ecffdd The first somewhat useable version of documentation in PDF.
Franz Glasner <fzglas.hg@dom66.de>
parents: 170
diff changeset
154 latex_show_urls = "footnote"
4b87a9ecffdd The first somewhat useable version of documentation in PDF.
Franz Glasner <fzglas.hg@dom66.de>
parents: 170
diff changeset
155 latex_show_pagerefs = True
4b87a9ecffdd The first somewhat useable version of documentation in PDF.
Franz Glasner <fzglas.hg@dom66.de>
parents: 170
diff changeset
156 latex_domain_indices = False
4b87a9ecffdd The first somewhat useable version of documentation in PDF.
Franz Glasner <fzglas.hg@dom66.de>
parents: 170
diff changeset
157 latex_documents = [
188
8e172ca6c944 FIX: Name of PDF output
Franz Glasner <fzglas.hg@dom66.de>
parents: 187
diff changeset
158 ("_latex/index-latex", "PygmentsLexerPseudocode2.tex", "The Pygments Pseudocode Lexer", "Franz Glasner", "manual", True),
171
4b87a9ecffdd The first somewhat useable version of documentation in PDF.
Franz Glasner <fzglas.hg@dom66.de>
parents: 170
diff changeset
159 ]
181
dcbc66f851eb A style file for (Lua)LaTeX that loads the required fonts.
Franz Glasner <fzglas.hg@dom66.de>
parents: 176
diff changeset
160 latex_additional_files = [
187
418846a2623c Also link to exampled from the PDF properly
Franz Glasner <fzglas.hg@dom66.de>
parents: 186
diff changeset
161 "_latex/my-doc-fonts.sty",
418846a2623c Also link to exampled from the PDF properly
Franz Glasner <fzglas.hg@dom66.de>
parents: 186
diff changeset
162 "examples/example-1.pseudocode", # linked via \url{}
418846a2623c Also link to exampled from the PDF properly
Franz Glasner <fzglas.hg@dom66.de>
parents: 186
diff changeset
163 "examples/algorithm-dinic.pseudocode",
418846a2623c Also link to exampled from the PDF properly
Franz Glasner <fzglas.hg@dom66.de>
parents: 186
diff changeset
164 "examples/algorithm-ford-fulkerson.pseudocode",
418846a2623c Also link to exampled from the PDF properly
Franz Glasner <fzglas.hg@dom66.de>
parents: 186
diff changeset
165 "examples/algorithm-edmonds-karp.pseudocode",
183
e3523930294a More comments on the needed Sphinx version
Franz Glasner <fzglas.hg@dom66.de>
parents: 182
diff changeset
166 ]
63
414bf3cbb152 Add a custom lexer to the Sphinx application dynamically with "no_end" set to True
Franz Glasner <fzglas.hg@dom66.de>
parents: 60
diff changeset
167
414bf3cbb152 Add a custom lexer to the Sphinx application dynamically with "no_end" set to True
Franz Glasner <fzglas.hg@dom66.de>
parents: 60
diff changeset
168 def setup(app):
68
93ade4c595b7 Reorg conf.py: import globally
Franz Glasner <fzglas.hg@dom66.de>
parents: 63
diff changeset
169 #
167
ddefcc20367c More static and/or dynamic metadata into README and project's init: release date, revision.
Franz Glasner <fzglas.hg@dom66.de>
parents: 166
diff changeset
170 # Custom release_date and commit id variables with a custom substitution
ddefcc20367c More static and/or dynamic metadata into README and project's init: release date, revision.
Franz Glasner <fzglas.hg@dom66.de>
parents: 166
diff changeset
171 # |release_date| and |release_rev|'.
ddefcc20367c More static and/or dynamic metadata into README and project's init: release date, revision.
Franz Glasner <fzglas.hg@dom66.de>
parents: 166
diff changeset
172 #
ddefcc20367c More static and/or dynamic metadata into README and project's init: release date, revision.
Franz Glasner <fzglas.hg@dom66.de>
parents: 166
diff changeset
173 app.add_config_value('release_date', '', 'env')
ddefcc20367c More static and/or dynamic metadata into README and project's init: release date, revision.
Franz Glasner <fzglas.hg@dom66.de>
parents: 166
diff changeset
174 app.add_config_value('release_rev', '', 'env')
ddefcc20367c More static and/or dynamic metadata into README and project's init: release date, revision.
Franz Glasner <fzglas.hg@dom66.de>
parents: 166
diff changeset
175
ddefcc20367c More static and/or dynamic metadata into README and project's init: release date, revision.
Franz Glasner <fzglas.hg@dom66.de>
parents: 166
diff changeset
176 #
63
414bf3cbb152 Add a custom lexer to the Sphinx application dynamically with "no_end" set to True
Franz Glasner <fzglas.hg@dom66.de>
parents: 60
diff changeset
177 # Add a custom lexer: AlgPseudocodeLexer with custom init option "no_end"
121
a3ed7d8231d7 Comment
Franz Glasner <fzglas.hg@dom66.de>
parents: 119
diff changeset
178 # Given lexer must be callable: so use an indirection with "partial".
a3ed7d8231d7 Comment
Franz Glasner <fzglas.hg@dom66.de>
parents: 119
diff changeset
179 #
a3ed7d8231d7 Comment
Franz Glasner <fzglas.hg@dom66.de>
parents: 119
diff changeset
180 # See also:
a3ed7d8231d7 Comment
Franz Glasner <fzglas.hg@dom66.de>
parents: 119
diff changeset
181 # - https://stackoverflow.com/questions/11413203/sphinx-pygments-lexer-filter-extension
68
93ade4c595b7 Reorg conf.py: import globally
Franz Glasner <fzglas.hg@dom66.de>
parents: 63
diff changeset
182 #
63
414bf3cbb152 Add a custom lexer to the Sphinx application dynamically with "no_end" set to True
Franz Glasner <fzglas.hg@dom66.de>
parents: 60
diff changeset
183 app.add_lexer("NoEndAlgPseudocode",
414bf3cbb152 Add a custom lexer to the Sphinx application dynamically with "no_end" set to True
Franz Glasner <fzglas.hg@dom66.de>
parents: 60
diff changeset
184 functools.partial(AlgPseudocodeLexer, no_end=True))
160
b4028838e0c8 Implement lexer option "prohibit_raiseonerror_filter".
Franz Glasner <fzglas.hg@dom66.de>
parents: 157
diff changeset
185 # For developing a lexer with smoother error handling
b4028838e0c8 Implement lexer option "prohibit_raiseonerror_filter".
Franz Glasner <fzglas.hg@dom66.de>
parents: 157
diff changeset
186 app.add_lexer("no-raiseonerror-algpseudocode",
b4028838e0c8 Implement lexer option "prohibit_raiseonerror_filter".
Franz Glasner <fzglas.hg@dom66.de>
parents: 157
diff changeset
187 functools.partial(AlgPseudocodeLexer,
b4028838e0c8 Implement lexer option "prohibit_raiseonerror_filter".
Franz Glasner <fzglas.hg@dom66.de>
parents: 157
diff changeset
188 prohibit_raiseonerror_filter=True))
166
6a7dace0141e Also implement filters to replace tokens in a token stream: TokenReplaceFilter and ErrorToGenericErrorTokenFilter
Franz Glasner <fzglas.hg@dom66.de>
parents: 164
diff changeset
189 #
6a7dace0141e Also implement filters to replace tokens in a token stream: TokenReplaceFilter and ErrorToGenericErrorTokenFilter
Franz Glasner <fzglas.hg@dom66.de>
parents: 164
diff changeset
190 # To test with the custom filter that maps
6a7dace0141e Also implement filters to replace tokens in a token stream: TokenReplaceFilter and ErrorToGenericErrorTokenFilter
Franz Glasner <fzglas.hg@dom66.de>
parents: 164
diff changeset
191 # Token.Error to Token.Generic.Error
6a7dace0141e Also implement filters to replace tokens in a token stream: TokenReplaceFilter and ErrorToGenericErrorTokenFilter
Franz Glasner <fzglas.hg@dom66.de>
parents: 164
diff changeset
192 #
6a7dace0141e Also implement filters to replace tokens in a token stream: TokenReplaceFilter and ErrorToGenericErrorTokenFilter
Franz Glasner <fzglas.hg@dom66.de>
parents: 164
diff changeset
193 app.add_lexer("genericerror-algpseudocode",
6a7dace0141e Also implement filters to replace tokens in a token stream: TokenReplaceFilter and ErrorToGenericErrorTokenFilter
Franz Glasner <fzglas.hg@dom66.de>
parents: 164
diff changeset
194 functools.partial(AlgPseudocodeLexer,
6a7dace0141e Also implement filters to replace tokens in a token stream: TokenReplaceFilter and ErrorToGenericErrorTokenFilter
Franz Glasner <fzglas.hg@dom66.de>
parents: 164
diff changeset
195 filters=["errortogenericerror"]))
185
b27557f6d393 Allow to build the documentation when the project is not installed
Franz Glasner <fzglas.hg@dom66.de>
parents: 183
diff changeset
196
b27557f6d393 Allow to build the documentation when the project is not installed
Franz Glasner <fzglas.hg@dom66.de>
parents: 183
diff changeset
197 #
b27557f6d393 Allow to build the documentation when the project is not installed
Franz Glasner <fzglas.hg@dom66.de>
parents: 183
diff changeset
198 # Prepare for building docs while the package is not installed:
b27557f6d393 Allow to build the documentation when the project is not installed
Franz Glasner <fzglas.hg@dom66.de>
parents: 183
diff changeset
199 # Install by "hand" into pygments!
b27557f6d393 Allow to build the documentation when the project is not installed
Franz Glasner <fzglas.hg@dom66.de>
parents: 183
diff changeset
200 # This is an ugly *HACK*!
b27557f6d393 Allow to build the documentation when the project is not installed
Franz Glasner <fzglas.hg@dom66.de>
parents: 183
diff changeset
201 #
b27557f6d393 Allow to build the documentation when the project is not installed
Franz Glasner <fzglas.hg@dom66.de>
parents: 183
diff changeset
202 # IMPORTANT: Synchronize names with pyproject.toml!
b27557f6d393 Allow to build the documentation when the project is not installed
Franz Glasner <fzglas.hg@dom66.de>
parents: 183
diff changeset
203 #
b27557f6d393 Allow to build the documentation when the project is not installed
Franz Glasner <fzglas.hg@dom66.de>
parents: 183
diff changeset
204 try:
b27557f6d393 Allow to build the documentation when the project is not installed
Franz Glasner <fzglas.hg@dom66.de>
parents: 183
diff changeset
205 if not pygments.lexers.find_lexer_class("AlgPseudocode"):
b27557f6d393 Allow to build the documentation when the project is not installed
Franz Glasner <fzglas.hg@dom66.de>
parents: 183
diff changeset
206 sphinx.util.logging.getLogger("conf-setup").info(
b27557f6d393 Allow to build the documentation when the project is not installed
Franz Glasner <fzglas.hg@dom66.de>
parents: 183
diff changeset
207 "%s","Installing lexer `AlgPseudocode' and language variants")
b27557f6d393 Allow to build the documentation when the project is not installed
Franz Glasner <fzglas.hg@dom66.de>
parents: 183
diff changeset
208 for clsname, lexer in (
b27557f6d393 Allow to build the documentation when the project is not installed
Franz Glasner <fzglas.hg@dom66.de>
parents: 183
diff changeset
209 ("AlgPseudocodeLexer", AlgPseudocodeLexer),
b27557f6d393 Allow to build the documentation when the project is not installed
Franz Glasner <fzglas.hg@dom66.de>
parents: 183
diff changeset
210 ("AlgPseudocodeLexer_DE", AlgPseudocodeLexer_DE),
b27557f6d393 Allow to build the documentation when the project is not installed
Franz Glasner <fzglas.hg@dom66.de>
parents: 183
diff changeset
211 ("AlgPseudocodeLexer_FR", AlgPseudocodeLexer_FR)):
b27557f6d393 Allow to build the documentation when the project is not installed
Franz Glasner <fzglas.hg@dom66.de>
parents: 183
diff changeset
212 pygments.lexers.LEXERS[clsname] = (
b27557f6d393 Allow to build the documentation when the project is not installed
Franz Glasner <fzglas.hg@dom66.de>
parents: 183
diff changeset
213 "pygments_lexer_pseudocode2.lexers.algpseudocode",
b27557f6d393 Allow to build the documentation when the project is not installed
Franz Glasner <fzglas.hg@dom66.de>
parents: 183
diff changeset
214 lexer.name,
b27557f6d393 Allow to build the documentation when the project is not installed
Franz Glasner <fzglas.hg@dom66.de>
parents: 183
diff changeset
215 tuple(lexer.aliases),
b27557f6d393 Allow to build the documentation when the project is not installed
Franz Glasner <fzglas.hg@dom66.de>
parents: 183
diff changeset
216 tuple(lexer.filenames),
b27557f6d393 Allow to build the documentation when the project is not installed
Franz Glasner <fzglas.hg@dom66.de>
parents: 183
diff changeset
217 tuple(lexer.mimetypes))
b27557f6d393 Allow to build the documentation when the project is not installed
Franz Glasner <fzglas.hg@dom66.de>
parents: 183
diff changeset
218 if not pygments.lexers.find_lexer_class("FrPseudocode"):
b27557f6d393 Allow to build the documentation when the project is not installed
Franz Glasner <fzglas.hg@dom66.de>
parents: 183
diff changeset
219 sphinx.util.logging.getLogger("conf-setup").info(
b27557f6d393 Allow to build the documentation when the project is not installed
Franz Glasner <fzglas.hg@dom66.de>
parents: 183
diff changeset
220 "%s","Installing lexer `FrPseudocode'")
b27557f6d393 Allow to build the documentation when the project is not installed
Franz Glasner <fzglas.hg@dom66.de>
parents: 183
diff changeset
221 for clsname, lexer in (
b27557f6d393 Allow to build the documentation when the project is not installed
Franz Glasner <fzglas.hg@dom66.de>
parents: 183
diff changeset
222 ("FrPseudocodeLexer", FrPseudocodeLexer),):
b27557f6d393 Allow to build the documentation when the project is not installed
Franz Glasner <fzglas.hg@dom66.de>
parents: 183
diff changeset
223 pygments.lexers.LEXERS[clsname] = (
b27557f6d393 Allow to build the documentation when the project is not installed
Franz Glasner <fzglas.hg@dom66.de>
parents: 183
diff changeset
224 "pygments_lexer_pseudocode2.lexers.fr_pseudocode",
b27557f6d393 Allow to build the documentation when the project is not installed
Franz Glasner <fzglas.hg@dom66.de>
parents: 183
diff changeset
225 lexer.name,
b27557f6d393 Allow to build the documentation when the project is not installed
Franz Glasner <fzglas.hg@dom66.de>
parents: 183
diff changeset
226 tuple(lexer.aliases),
b27557f6d393 Allow to build the documentation when the project is not installed
Franz Glasner <fzglas.hg@dom66.de>
parents: 183
diff changeset
227 tuple(lexer.filenames),
b27557f6d393 Allow to build the documentation when the project is not installed
Franz Glasner <fzglas.hg@dom66.de>
parents: 183
diff changeset
228 tuple(lexer.mimetypes))
b27557f6d393 Allow to build the documentation when the project is not installed
Franz Glasner <fzglas.hg@dom66.de>
parents: 183
diff changeset
229 if not pygments.filters.find_filter_class("tokenreplace"):
b27557f6d393 Allow to build the documentation when the project is not installed
Franz Glasner <fzglas.hg@dom66.de>
parents: 183
diff changeset
230 sphinx.util.logging.getLogger("conf-setup").info(
b27557f6d393 Allow to build the documentation when the project is not installed
Franz Glasner <fzglas.hg@dom66.de>
parents: 183
diff changeset
231 "%s","Installing filter `tokenreplace'")
b27557f6d393 Allow to build the documentation when the project is not installed
Franz Glasner <fzglas.hg@dom66.de>
parents: 183
diff changeset
232 pygments.filters.FILTERS["tokenreplace"] = TokenReplaceFilter
b27557f6d393 Allow to build the documentation when the project is not installed
Franz Glasner <fzglas.hg@dom66.de>
parents: 183
diff changeset
233 if not pygments.filters.find_filter_class("errortogenericerror"):
b27557f6d393 Allow to build the documentation when the project is not installed
Franz Glasner <fzglas.hg@dom66.de>
parents: 183
diff changeset
234 sphinx.util.logging.getLogger("conf-setup").info(
b27557f6d393 Allow to build the documentation when the project is not installed
Franz Glasner <fzglas.hg@dom66.de>
parents: 183
diff changeset
235 "%s","Installing filter `errortogenericerror'")
b27557f6d393 Allow to build the documentation when the project is not installed
Franz Glasner <fzglas.hg@dom66.de>
parents: 183
diff changeset
236 pygments.filters.FILTERS["errortogenericerror"] = \
b27557f6d393 Allow to build the documentation when the project is not installed
Franz Glasner <fzglas.hg@dom66.de>
parents: 183
diff changeset
237 ErrorToGenericErrorTokenFilter
b27557f6d393 Allow to build the documentation when the project is not installed
Franz Glasner <fzglas.hg@dom66.de>
parents: 183
diff changeset
238 except Exception as ex:
b27557f6d393 Allow to build the documentation when the project is not installed
Franz Glasner <fzglas.hg@dom66.de>
parents: 183
diff changeset
239 sphinx.util.logging.getLogger("conf-setup").error("%s", str(ex))
b27557f6d393 Allow to build the documentation when the project is not installed
Franz Glasner <fzglas.hg@dom66.de>
parents: 183
diff changeset
240 sphinx.util.logging.getLogger("conf-setup").error(
b27557f6d393 Allow to build the documentation when the project is not installed
Franz Glasner <fzglas.hg@dom66.de>
parents: 183
diff changeset
241 "%s",
b27557f6d393 Allow to build the documentation when the project is not installed
Franz Glasner <fzglas.hg@dom66.de>
parents: 183
diff changeset
242 "No lexers/filters from pygments_lexer_pseudocode2 available;"
b27557f6d393 Allow to build the documentation when the project is not installed
Franz Glasner <fzglas.hg@dom66.de>
parents: 183
diff changeset
243 " please install or call `pip install -e .' .")