Python/libs/pygments-lexer-pseudocode2: docs/conf.py annotate

annotate docs/conf.py @ 249:feaa552cbe98

Some overhowl of the docs configuration in conf.py. Sync with other projects.

author	Franz Glasner <fzglas.hg@dom66.de>
date	Sat, 16 May 2026 15:16:42 +0200
parents	76996a1e4ca7
children	5d3f7d80766f

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
213 d470250f8451 Title/metadata of PDF documentation builds: Franz Glasner <fzglas.hg@dom66.de> parents: 210 diff changeset	36 current_date = 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'
249 feaa552cbe98 Some overhowl of the docs configuration in conf.py. Franz Glasner <fzglas.hg@dom66.de> parents: 247 diff changeset	46
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	47 #
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 # 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	49 # 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	50 #
249 feaa552cbe98 Some overhowl of the docs configuration in conf.py. Franz Glasner <fzglas.hg@dom66.de> parents: 247 diff changeset	51
feaa552cbe98 Some overhowl of the docs configuration in conf.py. Franz Glasner <fzglas.hg@dom66.de> parents: 247 diff changeset	52 #
feaa552cbe98 Some overhowl of the docs configuration in conf.py. Franz Glasner <fzglas.hg@dom66.de> parents: 247 diff changeset	53 # Optimistically assume that all keywords are expanded properly everywhere:
feaa552cbe98 Some overhowl of the docs configuration in conf.py. Franz Glasner <fzglas.hg@dom66.de> parents: 247 diff changeset	54 # do not define special VCSxxx keyword below.
feaa552cbe98 Some overhowl of the docs configuration in conf.py. Franz Glasner <fzglas.hg@dom66.de> parents: 247 diff changeset	55 #
feaa552cbe98 Some overhowl of the docs configuration in conf.py. Franz Glasner <fzglas.hg@dom66.de> parents: 247 diff changeset	56 define_rest_keywords = False
49 5c0f26a21e81 Determine "release" dynamically from the package's "__version__" Franz Glasner <fzglas.hg@dom66.de> parents: 48 diff changeset	57 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	58 "rt",
5c0f26a21e81 Determine "release" dynamically from the package's "__version__" Franz Glasner <fzglas.hg@dom66.de> parents: 48 diff changeset	59 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	60 verfiledata = relfp.read()
249 feaa552cbe98 Some overhowl of the docs configuration in conf.py. Franz Glasner <fzglas.hg@dom66.de> parents: 247 diff changeset	61 release = ast.literal_eval(
feaa552cbe98 Some overhowl of the docs configuration in conf.py. Franz Glasner <fzglas.hg@dom66.de> parents: 247 diff changeset	62 re.search(r"""^\s__version__\s=\s(("\|')[^"']\2)""",
feaa552cbe98 Some overhowl of the docs configuration in conf.py. Franz Glasner <fzglas.hg@dom66.de> parents: 247 diff changeset	63 verfiledata,
feaa552cbe98 Some overhowl of the docs configuration in conf.py. Franz Glasner <fzglas.hg@dom66.de> parents: 247 diff changeset	64 re.MULTILINE).group(1))
feaa552cbe98 Some overhowl of the docs configuration in conf.py. Franz Glasner <fzglas.hg@dom66.de> parents: 247 diff changeset	65 release_date = today = ast.literal_eval(
feaa552cbe98 Some overhowl of the docs configuration in conf.py. Franz Glasner <fzglas.hg@dom66.de> parents: 247 diff changeset	66 re.search(r"""^\s__date__\s=\s(("\|')[^"']\2)""",
feaa552cbe98 Some overhowl of the docs configuration in conf.py. Franz Glasner <fzglas.hg@dom66.de> parents: 247 diff changeset	67 verfiledata,
feaa552cbe98 Some overhowl of the docs configuration in conf.py. Franz Glasner <fzglas.hg@dom66.de> parents: 247 diff changeset	68 re.MULTILINE).group(1))
feaa552cbe98 Some overhowl of the docs configuration in conf.py. Franz Glasner <fzglas.hg@dom66.de> parents: 247 diff changeset	69 if (not release_date
feaa552cbe98 Some overhowl of the docs configuration in conf.py. Franz Glasner <fzglas.hg@dom66.de> parents: 247 diff changeset	70 or (release_date.startswith("\|") and release_date.endswith("\|"))):
feaa552cbe98 Some overhowl of the docs configuration in conf.py. Franz Glasner <fzglas.hg@dom66.de> parents: 247 diff changeset	71 release_date = today = "dev-%s" % (current_date,)
feaa552cbe98 Some overhowl of the docs configuration in conf.py. Franz Glasner <fzglas.hg@dom66.de> parents: 247 diff changeset	72 release_rev = ast.literal_eval(
feaa552cbe98 Some overhowl of the docs configuration in conf.py. Franz Glasner <fzglas.hg@dom66.de> parents: 247 diff changeset	73 re.search(r"""^\s__revision__\s=\s(("\|')[^"']\2)""",
feaa552cbe98 Some overhowl of the docs configuration in conf.py. Franz Glasner <fzglas.hg@dom66.de> parents: 247 diff changeset	74 verfiledata,
feaa552cbe98 Some overhowl of the docs configuration in conf.py. Franz Glasner <fzglas.hg@dom66.de> parents: 247 diff changeset	75 re.MULTILINE).group(1))
feaa552cbe98 Some overhowl of the docs configuration in conf.py. Franz Glasner <fzglas.hg@dom66.de> parents: 247 diff changeset	76 if (not release_rev
feaa552cbe98 Some overhowl of the docs configuration in conf.py. Franz Glasner <fzglas.hg@dom66.de> parents: 247 diff changeset	77 or (release_rev.startswith("\|") or release_rev.endswith("\|"))):
feaa552cbe98 Some overhowl of the docs configuration in conf.py. Franz Glasner <fzglas.hg@dom66.de> parents: 247 diff changeset	78 #
feaa552cbe98 Some overhowl of the docs configuration in conf.py. Franz Glasner <fzglas.hg@dom66.de> parents: 247 diff changeset	79 # Above assumption is not true: "hg kwarchive" may not have been called.
feaa552cbe98 Some overhowl of the docs configuration in conf.py. Franz Glasner <fzglas.hg@dom66.de> parents: 247 diff changeset	80 # Try to determine from VCS.
feaa552cbe98 Some overhowl of the docs configuration in conf.py. Franz Glasner <fzglas.hg@dom66.de> parents: 247 diff changeset	81 #
feaa552cbe98 Some overhowl of the docs configuration in conf.py. Franz Glasner <fzglas.hg@dom66.de> parents: 247 diff changeset	82 import subprocess
feaa552cbe98 Some overhowl of the docs configuration in conf.py. Franz Glasner <fzglas.hg@dom66.de> parents: 247 diff changeset	83 try:
feaa552cbe98 Some overhowl of the docs configuration in conf.py. Franz Glasner <fzglas.hg@dom66.de> parents: 247 diff changeset	84 release_rev = subprocess.check_output(
feaa552cbe98 Some overhowl of the docs configuration in conf.py. Franz Glasner <fzglas.hg@dom66.de> parents: 247 diff changeset	85 ["hg", "id", "-i"], stderr=subprocess.STDOUT)
feaa552cbe98 Some overhowl of the docs configuration in conf.py. Franz Glasner <fzglas.hg@dom66.de> parents: 247 diff changeset	86 except Exception:
feaa552cbe98 Some overhowl of the docs configuration in conf.py. Franz Glasner <fzglas.hg@dom66.de> parents: 247 diff changeset	87 release_rev = "<UNKNOWN>"
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	88 else:
249 feaa552cbe98 Some overhowl of the docs configuration in conf.py. Franz Glasner <fzglas.hg@dom66.de> parents: 247 diff changeset	89 if sys.version_info[0] >= 3:
feaa552cbe98 Some overhowl of the docs configuration in conf.py. Franz Glasner <fzglas.hg@dom66.de> parents: 247 diff changeset	90 release_rev = release_rev.decode("ascii")
feaa552cbe98 Some overhowl of the docs configuration in conf.py. Franz Glasner <fzglas.hg@dom66.de> parents: 247 diff changeset	91 release_rev = "dev-%s" % (release_rev.strip(),)
feaa552cbe98 Some overhowl of the docs configuration in conf.py. Franz Glasner <fzglas.hg@dom66.de> parents: 247 diff changeset	92 define_rest_keywords = True
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	93
51 b4c255f8bdc4 Also define "version" (identical to "release" yet) Franz Glasner <fzglas.hg@dom66.de> parents: 50 diff changeset	94 version = release
157 902147c24f9b Disable a default domain when generating the docs Franz Glasner <fzglas.hg@dom66.de> parents: 155 diff changeset	95 primary_domain = None
60 0ff291eac663 Minimal Sphinx configuration for the first tests Franz Glasner <fzglas.hg@dom66.de> parents: 51 diff changeset	96
45 6ac1ea5d2d4a Begin documentation: add the Sphinx generated configuration as-is Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	97 # -- General configuration ---------------------------------------------------
6ac1ea5d2d4a Begin documentation: add the Sphinx generated configuration as-is Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	98 # 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	99
60 0ff291eac663 Minimal Sphinx configuration for the first tests Franz Glasner <fzglas.hg@dom66.de> parents: 51 diff changeset	100 extensions = [
0ff291eac663 Minimal Sphinx configuration for the first tests Franz Glasner <fzglas.hg@dom66.de> parents: 51 diff changeset	101 "sphinx.ext.todo",
0ff291eac663 Minimal Sphinx configuration for the first tests Franz Glasner <fzglas.hg@dom66.de> parents: 51 diff changeset	102 ]
45 6ac1ea5d2d4a Begin documentation: add the Sphinx generated configuration as-is Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	103
6ac1ea5d2d4a Begin documentation: add the Sphinx generated configuration as-is Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	104 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	105 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	106
132 a3e765f1ad23 Explicitely set "highlight_languge" to "none" in the docs configuration. Franz Glasner <fzglas.hg@dom66.de> parents: 121 diff changeset	107 highlight_language = "none"
a3e765f1ad23 Explicitely set "highlight_languge" to "none" in the docs configuration. Franz Glasner <fzglas.hg@dom66.de> parents: 121 diff changeset	108
145 c4f6f5e771b0 Also define the :algpseudocode: role globally in the package documentation. Franz Glasner <fzglas.hg@dom66.de> parents: 144 diff changeset	109 rst_prolog = """
c4f6f5e771b0 Also define the :algpseudocode: role globally in the package documentation. Franz Glasner <fzglas.hg@dom66.de> parents: 144 diff changeset	110 .. 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	111 .. \|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	112 .. \|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	113 """ % (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	114 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	115 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	116 .. \|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	117 .. \|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	118 """ % (release_date, release_rev)
144 b616f9645e37 More referencing with internal and external links Franz Glasner <fzglas.hg@dom66.de> parents: 143 diff changeset	119 rst_epilog = """
145 c4f6f5e771b0 Also define the :algpseudocode: role globally in the package documentation. Franz Glasner <fzglas.hg@dom66.de> parents: 144 diff changeset	120 .. _Pygments: https://pygments.org/
144 b616f9645e37 More referencing with internal and external links Franz Glasner <fzglas.hg@dom66.de> parents: 143 diff changeset	121 .. _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	122 .. _Python: https://www.python.org/
150 4acf578ae93f Much more details in the documentation Franz Glasner <fzglas.hg@dom66.de> parents: 145 diff changeset	123 .. _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	124 """
b616f9645e37 More referencing with internal and external links Franz Glasner <fzglas.hg@dom66.de> parents: 143 diff changeset	125
60 0ff291eac663 Minimal Sphinx configuration for the first tests Franz Glasner <fzglas.hg@dom66.de> parents: 51 diff changeset	126
0ff291eac663 Minimal Sphinx configuration for the first tests Franz Glasner <fzglas.hg@dom66.de> parents: 51 diff changeset	127 # --- Options for todo extension ---------------------------------------------
0ff291eac663 Minimal Sphinx configuration for the first tests Franz Glasner <fzglas.hg@dom66.de> parents: 51 diff changeset	128 todo_include_todos = True
45 6ac1ea5d2d4a Begin documentation: add the Sphinx generated configuration as-is Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	129
6ac1ea5d2d4a Begin documentation: add the Sphinx generated configuration as-is Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	130
6ac1ea5d2d4a Begin documentation: add the Sphinx generated configuration as-is Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	131 # -- Options for HTML output -------------------------------------------------
6ac1ea5d2d4a Begin documentation: add the Sphinx generated configuration as-is Franz Glasner <fzglas.hg@dom66.de> parents: diff changeset	132 # 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	133
139 d8ac51cba0ff Customize the HTML title for the haiku theme Franz Glasner <fzglas.hg@dom66.de> parents: 135 diff changeset	134 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	135 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	136 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	137 html_show_sourcelink = False
139 d8ac51cba0ff Customize the HTML title for the haiku theme Franz Glasner <fzglas.hg@dom66.de> parents: 135 diff changeset	138
121 a3ed7d8231d7 Comment Franz Glasner <fzglas.hg@dom66.de> parents: 119 diff changeset	139 #html_theme = 'alabaster'
60 0ff291eac663 Minimal Sphinx configuration for the first tests Franz Glasner <fzglas.hg@dom66.de> parents: 51 diff changeset	140 html_theme = 'haiku'
170 f761694373e0 Do not justify the documentation output. Franz Glasner <fzglas.hg@dom66.de> parents: 167 diff changeset	141 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	142 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	143 html_short_title = html_title
247 76996a1e4ca7 Use "rev " instead of "rv:" in the revision footer Franz Glasner <fzglas.hg@dom66.de> parents: 246 diff changeset	144 html_last_updated_fmt = "%s (rev %s)" % (current_date, 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	145 #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	146 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	147
171 4b87a9ecffdd The first somewhat useable version of documentation in PDF. Franz Glasner <fzglas.hg@dom66.de> parents: 170 diff changeset	148 # --- Options for LaTeX output -----------------------------------------------
4b87a9ecffdd The first somewhat useable version of documentation in PDF. Franz Glasner <fzglas.hg@dom66.de> parents: 170 diff changeset	149 # 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	150 latex_engine = 'lualatex'
4b87a9ecffdd The first somewhat useable version of documentation in PDF. Franz Glasner <fzglas.hg@dom66.de> parents: 170 diff changeset	151 latex_elements = {
4b87a9ecffdd The first somewhat useable version of documentation in PDF. Franz Glasner <fzglas.hg@dom66.de> parents: 170 diff changeset	152 "papersize": "a4paper",
4b87a9ecffdd The first somewhat useable version of documentation in PDF. Franz Glasner <fzglas.hg@dom66.de> parents: 170 diff changeset	153 "babel": r"\usepackage{babel}",
244 53bb764cfaf6 WS Franz Glasner <fzglas.hg@dom66.de> parents: 224 diff changeset	154 "fontpkg": r"\usepackage[fonts=adobesourcepro]{my-doc-fonts}",
171 4b87a9ecffdd The first somewhat useable version of documentation in PDF. Franz Glasner <fzglas.hg@dom66.de> parents: 170 diff changeset	155 "releasename": "Version",
200 a5700f19e616 Use "Sonny" fncychap style Franz Glasner <fzglas.hg@dom66.de> parents: 197 diff changeset	156 "fncychap": r"\usepackage[Sonny]{fncychap}",
216 8ef73270beae Make my-doc-style.sty more flexible by providing the "stdtitle" option to switch off the customized titlepage content Franz Glasner <fzglas.hg@dom66.de> parents: 213 diff changeset	157 "preamble": r"\usepackage[stdtitle=false]{my-doc-style}",
249 feaa552cbe98 Some overhowl of the docs configuration in conf.py. Franz Glasner <fzglas.hg@dom66.de> parents: 247 diff changeset	158 "maketitle": r"\builddate{%s}\vcsrevision{%s}\sphinxmaketitle"
feaa552cbe98 Some overhowl of the docs configuration in conf.py. Franz Glasner <fzglas.hg@dom66.de> parents: 247 diff changeset	159 % (current_date, release_rev),
171 4b87a9ecffdd The first somewhat useable version of documentation in PDF. Franz Glasner <fzglas.hg@dom66.de> parents: 170 diff changeset	160 }
4b87a9ecffdd The first somewhat useable version of documentation in PDF. Franz Glasner <fzglas.hg@dom66.de> parents: 170 diff changeset	161 latex_theme = "manual"
4b87a9ecffdd The first somewhat useable version of documentation in PDF. Franz Glasner <fzglas.hg@dom66.de> parents: 170 diff changeset	162 latex_show_urls = "footnote"
4b87a9ecffdd The first somewhat useable version of documentation in PDF. Franz Glasner <fzglas.hg@dom66.de> parents: 170 diff changeset	163 latex_show_pagerefs = True
4b87a9ecffdd The first somewhat useable version of documentation in PDF. Franz Glasner <fzglas.hg@dom66.de> parents: 170 diff changeset	164 latex_domain_indices = False
4b87a9ecffdd The first somewhat useable version of documentation in PDF. Franz Glasner <fzglas.hg@dom66.de> parents: 170 diff changeset	165 latex_documents = [
188 8e172ca6c944 FIX: Name of PDF output Franz Glasner <fzglas.hg@dom66.de> parents: 187 diff changeset	166 ("_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	167 ]
181 dcbc66f851eb A style file for (Lua)LaTeX that loads the required fonts. Franz Glasner <fzglas.hg@dom66.de> parents: 176 diff changeset	168 latex_additional_files = [
187 418846a2623c Also link to exampled from the PDF properly Franz Glasner <fzglas.hg@dom66.de> parents: 186 diff changeset	169 "_latex/my-doc-fonts.sty",
213 d470250f8451 Title/metadata of PDF documentation builds: Franz Glasner <fzglas.hg@dom66.de> parents: 210 diff changeset	170 "_latex/my-doc-style.sty",
187 418846a2623c Also link to exampled from the PDF properly Franz Glasner <fzglas.hg@dom66.de> parents: 186 diff changeset	171 "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	172 "examples/algorithm-dinic.pseudocode",
418846a2623c Also link to exampled from the PDF properly Franz Glasner <fzglas.hg@dom66.de> parents: 186 diff changeset	173 "examples/algorithm-ford-fulkerson.pseudocode",
418846a2623c Also link to exampled from the PDF properly Franz Glasner <fzglas.hg@dom66.de> parents: 186 diff changeset	174 "examples/algorithm-edmonds-karp.pseudocode",
183 e3523930294a More comments on the needed Sphinx version Franz Glasner <fzglas.hg@dom66.de> parents: 182 diff changeset	175 ]
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	176
249 feaa552cbe98 Some overhowl of the docs configuration in conf.py. Franz Glasner <fzglas.hg@dom66.de> parents: 247 diff changeset	177
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	178 def setup(app):
68 93ade4c595b7 Reorg conf.py: import globally Franz Glasner <fzglas.hg@dom66.de> parents: 63 diff changeset	179 #
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	180 # 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	181 # \|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	182 #
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	183 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	184 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	185
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	186 #
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	187 # Add a custom lexer: AlgPseudocodeLexer with custom init option "no_end"
121 a3ed7d8231d7 Comment Franz Glasner <fzglas.hg@dom66.de> parents: 119 diff changeset	188 # Given lexer must be callable: so use an indirection with "partial".
a3ed7d8231d7 Comment Franz Glasner <fzglas.hg@dom66.de> parents: 119 diff changeset	189 #
a3ed7d8231d7 Comment Franz Glasner <fzglas.hg@dom66.de> parents: 119 diff changeset	190 # See also:
a3ed7d8231d7 Comment Franz Glasner <fzglas.hg@dom66.de> parents: 119 diff changeset	191 # - 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	192 #
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	193 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	194 functools.partial(AlgPseudocodeLexer, no_end=True))
160 b4028838e0c8 Implement lexer option "prohibit_raiseonerror_filter". Franz Glasner <fzglas.hg@dom66.de> parents: 157 diff changeset	195 # 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	196 app.add_lexer("no-raiseonerror-algpseudocode",
b4028838e0c8 Implement lexer option "prohibit_raiseonerror_filter". Franz Glasner <fzglas.hg@dom66.de> parents: 157 diff changeset	197 functools.partial(AlgPseudocodeLexer,
b4028838e0c8 Implement lexer option "prohibit_raiseonerror_filter". Franz Glasner <fzglas.hg@dom66.de> parents: 157 diff changeset	198 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	199 #
6a7dace0141e Also implement filters to replace tokens in a token stream: TokenReplaceFilter and ErrorToGenericErrorTokenFilter Franz Glasner <fzglas.hg@dom66.de> parents: 164 diff changeset	200 # 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	201 # 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	202 #
6a7dace0141e Also implement filters to replace tokens in a token stream: TokenReplaceFilter and ErrorToGenericErrorTokenFilter Franz Glasner <fzglas.hg@dom66.de> parents: 164 diff changeset	203 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	204 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	205 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	206
b27557f6d393 Allow to build the documentation when the project is not installed Franz Glasner <fzglas.hg@dom66.de> parents: 183 diff changeset	207 #
b27557f6d393 Allow to build the documentation when the project is not installed Franz Glasner <fzglas.hg@dom66.de> parents: 183 diff changeset	208 # 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	209 # 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	210 # 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	211 #
b27557f6d393 Allow to build the documentation when the project is not installed Franz Glasner <fzglas.hg@dom66.de> parents: 183 diff changeset	212 # 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	213 #
b27557f6d393 Allow to build the documentation when the project is not installed Franz Glasner <fzglas.hg@dom66.de> parents: 183 diff changeset	214 try:
b27557f6d393 Allow to build the documentation when the project is not installed Franz Glasner <fzglas.hg@dom66.de> parents: 183 diff changeset	215 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	216 sphinx.util.logging.getLogger("conf-setup").info(
249 feaa552cbe98 Some overhowl of the docs configuration in conf.py. Franz Glasner <fzglas.hg@dom66.de> parents: 247 diff changeset	217 "%s", "Installing lexer `AlgPseudocode' and language variants")
185 b27557f6d393 Allow to build the documentation when the project is not installed Franz Glasner <fzglas.hg@dom66.de> parents: 183 diff changeset	218 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	219 ("AlgPseudocodeLexer", AlgPseudocodeLexer),
b27557f6d393 Allow to build the documentation when the project is not installed Franz Glasner <fzglas.hg@dom66.de> parents: 183 diff changeset	220 ("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	221 ("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	222 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	223 "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	224 lexer.name,
b27557f6d393 Allow to build the documentation when the project is not installed Franz Glasner <fzglas.hg@dom66.de> parents: 183 diff changeset	225 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	226 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	227 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	228 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	229 sphinx.util.logging.getLogger("conf-setup").info(
249 feaa552cbe98 Some overhowl of the docs configuration in conf.py. Franz Glasner <fzglas.hg@dom66.de> parents: 247 diff changeset	230 "%s", "Installing lexer `FrPseudocode'")
185 b27557f6d393 Allow to build the documentation when the project is not installed Franz Glasner <fzglas.hg@dom66.de> parents: 183 diff changeset	231 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	232 ("FrPseudocodeLexer", FrPseudocodeLexer),):
b27557f6d393 Allow to build the documentation when the project is not installed Franz Glasner <fzglas.hg@dom66.de> parents: 183 diff changeset	233 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	234 "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	235 lexer.name,
b27557f6d393 Allow to build the documentation when the project is not installed Franz Glasner <fzglas.hg@dom66.de> parents: 183 diff changeset	236 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	237 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	238 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	239 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	240 sphinx.util.logging.getLogger("conf-setup").info(
249 feaa552cbe98 Some overhowl of the docs configuration in conf.py. Franz Glasner <fzglas.hg@dom66.de> parents: 247 diff changeset	241 "%s", "Installing filter `tokenreplace'")
185 b27557f6d393 Allow to build the documentation when the project is not installed Franz Glasner <fzglas.hg@dom66.de> parents: 183 diff changeset	242 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	243 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	244 sphinx.util.logging.getLogger("conf-setup").info(
249 feaa552cbe98 Some overhowl of the docs configuration in conf.py. Franz Glasner <fzglas.hg@dom66.de> parents: 247 diff changeset	245 "%s", "Installing filter `errortogenericerror'")
feaa552cbe98 Some overhowl of the docs configuration in conf.py. Franz Glasner <fzglas.hg@dom66.de> parents: 247 diff changeset	246 pygments.filters.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	247 ErrorToGenericErrorTokenFilter
b27557f6d393 Allow to build the documentation when the project is not installed Franz Glasner <fzglas.hg@dom66.de> parents: 183 diff changeset	248 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	249 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	250 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	251 "%s",
b27557f6d393 Allow to build the documentation when the project is not installed Franz Glasner <fzglas.hg@dom66.de> parents: 183 diff changeset	252 "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	253 " please install or call `pip install -e .' .")

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

annotate docs/conf.py @ 249:feaa552cbe98