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

annotate docs/conf.py @ 160:b4028838e0c8

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Implement lexer option "prohibit_raiseonerror_filter". Sphinx raises by default when an Error token is seen (by means of the "raiseonerror" filter that is applied by default to lexers in Sphinx). This option skips this and allows error locations to be seen and highlighted properly. While there convert most Generic.Error tokens to Error tokens because now they can be handled by a lexer with "prohibit_raiseonerror_filter=True".
author Franz Glasner <fzglas.hg@dom66.de>
date Fri, 08 May 2026 17:46:28 +0200
parents 902147c24f9b
children a4317957148b
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
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
7 import functools
49
5c0f26a21e81 Determine "release" dynamically from the package's "__version__"
Franz Glasner <fzglas.hg@dom66.de>
parents: 48
diff changeset
8 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
9 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
10 import sys
49
5c0f26a21e81 Determine "release" dynamically from the package's "__version__"
Franz Glasner <fzglas.hg@dom66.de>
parents: 48
diff changeset
11 import re
5c0f26a21e81 Determine "release" dynamically from the package's "__version__"
Franz Glasner <fzglas.hg@dom66.de>
parents: 48
diff changeset
12
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
13 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
14
68
93ade4c595b7 Reorg conf.py: import globally
Franz Glasner <fzglas.hg@dom66.de>
parents: 63
diff changeset
15 from pygments_lexer_pseudocode2.algpseudocode import AlgPseudocodeLexer
93ade4c595b7 Reorg conf.py: import globally
Franz Glasner <fzglas.hg@dom66.de>
parents: 63
diff changeset
16
93ade4c595b7 Reorg conf.py: import globally
Franz Glasner <fzglas.hg@dom66.de>
parents: 63
diff changeset
17
134
62407bd73ba8 Require Sphinx >= 2.1.
Franz Glasner <fzglas.hg@dom66.de>
parents: 132
diff changeset
18 needs_sphinx = '2.1'
155
16faae7ecdb6 Document why Sphinx>=2.1 is needed
Franz Glasner <fzglas.hg@dom66.de>
parents: 151
diff changeset
19 """2.1: - :py:meth:Sphinx.add_lexer` takes a class as argument
16faae7ecdb6 Document why Sphinx>=2.1 is needed
Franz Glasner <fzglas.hg@dom66.de>
parents: 151
diff changeset
20
16faae7ecdb6 Document why Sphinx>=2.1 is needed
Franz Glasner <fzglas.hg@dom66.de>
parents: 151
diff changeset
21 """
134
62407bd73ba8 Require Sphinx >= 2.1.
Franz Glasner <fzglas.hg@dom66.de>
parents: 132
diff changeset
22
62407bd73ba8 Require Sphinx >= 2.1.
Franz Glasner <fzglas.hg@dom66.de>
parents: 132
diff changeset
23
45
6ac1ea5d2d4a Begin documentation: add the Sphinx generated configuration as-is
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
24 # -- Project information -----------------------------------------------------
6ac1ea5d2d4a Begin documentation: add the Sphinx generated configuration as-is
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
25 # 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
26
6ac1ea5d2d4a Begin documentation: add the Sphinx generated configuration as-is
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
27 project = 'Pygments Pseudocode Lexer'
118
a861ac4d11fc Extend the copyright to Simon Wachter in the docs
Franz Glasner <fzglas.hg@dom66.de>
parents: 68
diff changeset
28 copyright = '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
29 author = 'Franz Glasner'
49
5c0f26a21e81 Determine "release" dynamically from the package's "__version__"
Franz Glasner <fzglas.hg@dom66.de>
parents: 48
diff changeset
30 # Determine "release" dynamically from the package's "__version__"
5c0f26a21e81 Determine "release" dynamically from the package's "__version__"
Franz Glasner <fzglas.hg@dom66.de>
parents: 48
diff changeset
31 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
32 "rt",
5c0f26a21e81 Determine "release" dynamically from the package's "__version__"
Franz Glasner <fzglas.hg@dom66.de>
parents: 48
diff changeset
33 encoding="utf-8") as relfp:
5c0f26a21e81 Determine "release" dynamically from the package's "__version__"
Franz Glasner <fzglas.hg@dom66.de>
parents: 48
diff changeset
34 release = ast.literal_eval(
5c0f26a21e81 Determine "release" dynamically from the package's "__version__"
Franz Glasner <fzglas.hg@dom66.de>
parents: 48
diff changeset
35 re.search(r"""^\s*__version__\s*=\s*(("|')[^"']*\2)""",
5c0f26a21e81 Determine "release" dynamically from the package's "__version__"
Franz Glasner <fzglas.hg@dom66.de>
parents: 48
diff changeset
36 relfp.read(),
5c0f26a21e81 Determine "release" dynamically from the package's "__version__"
Franz Glasner <fzglas.hg@dom66.de>
parents: 48
diff changeset
37 re.MULTILINE)
5c0f26a21e81 Determine "release" dynamically from the package's "__version__"
Franz Glasner <fzglas.hg@dom66.de>
parents: 48
diff changeset
38 .group(1)
5c0f26a21e81 Determine "release" dynamically from the package's "__version__"
Franz Glasner <fzglas.hg@dom66.de>
parents: 48
diff changeset
39 )
51
b4c255f8bdc4 Also define "version" (identical to "release" yet)
Franz Glasner <fzglas.hg@dom66.de>
parents: 50
diff changeset
40 version = release
b4c255f8bdc4 Also define "version" (identical to "release" yet)
Franz Glasner <fzglas.hg@dom66.de>
parents: 50
diff changeset
41 del relfp
157
902147c24f9b Disable a default domain when generating the docs
Franz Glasner <fzglas.hg@dom66.de>
parents: 155
diff changeset
42 primary_domain = None
60
0ff291eac663 Minimal Sphinx configuration for the first tests
Franz Glasner <fzglas.hg@dom66.de>
parents: 51
diff changeset
43
45
6ac1ea5d2d4a Begin documentation: add the Sphinx generated configuration as-is
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
44 # -- General configuration ---------------------------------------------------
6ac1ea5d2d4a Begin documentation: add the Sphinx generated configuration as-is
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
45 # 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
46
60
0ff291eac663 Minimal Sphinx configuration for the first tests
Franz Glasner <fzglas.hg@dom66.de>
parents: 51
diff changeset
47 extensions = [
0ff291eac663 Minimal Sphinx configuration for the first tests
Franz Glasner <fzglas.hg@dom66.de>
parents: 51
diff changeset
48 "sphinx.ext.todo",
0ff291eac663 Minimal Sphinx configuration for the first tests
Franz Glasner <fzglas.hg@dom66.de>
parents: 51
diff changeset
49 ]
45
6ac1ea5d2d4a Begin documentation: add the Sphinx generated configuration as-is
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
50
6ac1ea5d2d4a Begin documentation: add the Sphinx generated configuration as-is
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
51 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
52 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
53
132
a3e765f1ad23 Explicitely set "highlight_languge" to "none" in the docs configuration.
Franz Glasner <fzglas.hg@dom66.de>
parents: 121
diff changeset
54 highlight_language = "none"
a3e765f1ad23 Explicitely set "highlight_languge" to "none" in the docs configuration.
Franz Glasner <fzglas.hg@dom66.de>
parents: 121
diff changeset
55
145
c4f6f5e771b0 Also define the :algpseudocode: role globally in the package documentation.
Franz Glasner <fzglas.hg@dom66.de>
parents: 144
diff changeset
56 rst_prolog = """
c4f6f5e771b0 Also define the :algpseudocode: role globally in the package documentation.
Franz Glasner <fzglas.hg@dom66.de>
parents: 144
diff changeset
57 .. role:: algpseudocode(code)
c4f6f5e771b0 Also define the :algpseudocode: role globally in the package documentation.
Franz Glasner <fzglas.hg@dom66.de>
parents: 144
diff changeset
58 """
144
b616f9645e37 More referencing with internal and external links
Franz Glasner <fzglas.hg@dom66.de>
parents: 143
diff changeset
59 rst_epilog = """
145
c4f6f5e771b0 Also define the :algpseudocode: role globally in the package documentation.
Franz Glasner <fzglas.hg@dom66.de>
parents: 144
diff changeset
60 .. _Pygments: https://pygments.org/
144
b616f9645e37 More referencing with internal and external links
Franz Glasner <fzglas.hg@dom66.de>
parents: 143
diff changeset
61 .. _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
62 .. _Python: https://www.python.org/
150
4acf578ae93f Much more details in the documentation
Franz Glasner <fzglas.hg@dom66.de>
parents: 145
diff changeset
63 .. _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
64 """
b616f9645e37 More referencing with internal and external links
Franz Glasner <fzglas.hg@dom66.de>
parents: 143
diff changeset
65
60
0ff291eac663 Minimal Sphinx configuration for the first tests
Franz Glasner <fzglas.hg@dom66.de>
parents: 51
diff changeset
66
0ff291eac663 Minimal Sphinx configuration for the first tests
Franz Glasner <fzglas.hg@dom66.de>
parents: 51
diff changeset
67 # --- Options for todo extension ---------------------------------------------
0ff291eac663 Minimal Sphinx configuration for the first tests
Franz Glasner <fzglas.hg@dom66.de>
parents: 51
diff changeset
68 todo_include_todos = True
45
6ac1ea5d2d4a Begin documentation: add the Sphinx generated configuration as-is
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
69
6ac1ea5d2d4a Begin documentation: add the Sphinx generated configuration as-is
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
70
6ac1ea5d2d4a Begin documentation: add the Sphinx generated configuration as-is
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
71 # -- Options for HTML output -------------------------------------------------
6ac1ea5d2d4a Begin documentation: add the Sphinx generated configuration as-is
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
72 # 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
73
139
d8ac51cba0ff Customize the HTML title for the haiku theme
Franz Glasner <fzglas.hg@dom66.de>
parents: 135
diff changeset
74 html_static_path = ['_static']
151
4a8c122725b0 Move all the example files to "examples/"
Franz Glasner <fzglas.hg@dom66.de>
parents: 150
diff changeset
75 html_extra_path = ['../LICENSES', './examples']
139
d8ac51cba0ff Customize the HTML title for the haiku theme
Franz Glasner <fzglas.hg@dom66.de>
parents: 135
diff changeset
76
121
a3ed7d8231d7 Comment
Franz Glasner <fzglas.hg@dom66.de>
parents: 119
diff changeset
77 #html_theme = 'alabaster'
60
0ff291eac663 Minimal Sphinx configuration for the first tests
Franz Glasner <fzglas.hg@dom66.de>
parents: 51
diff changeset
78 html_theme = 'haiku'
139
d8ac51cba0ff Customize the HTML title for the haiku theme
Franz Glasner <fzglas.hg@dom66.de>
parents: 135
diff changeset
79 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
80 html_short_title = html_title
143
6da3b9dd4294 FIX: Do not use the default pygments style "sphinx"; was submitted erroneously
Franz Glasner <fzglas.hg@dom66.de>
parents: 141
diff changeset
81 #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
82 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
83
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
84
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
85 def setup(app):
68
93ade4c595b7 Reorg conf.py: import globally
Franz Glasner <fzglas.hg@dom66.de>
parents: 63
diff changeset
86 #
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
87 # Add a custom lexer: AlgPseudocodeLexer with custom init option "no_end"
121
a3ed7d8231d7 Comment
Franz Glasner <fzglas.hg@dom66.de>
parents: 119
diff changeset
88 # Given lexer must be callable: so use an indirection with "partial".
a3ed7d8231d7 Comment
Franz Glasner <fzglas.hg@dom66.de>
parents: 119
diff changeset
89 #
a3ed7d8231d7 Comment
Franz Glasner <fzglas.hg@dom66.de>
parents: 119
diff changeset
90 # See also:
a3ed7d8231d7 Comment
Franz Glasner <fzglas.hg@dom66.de>
parents: 119
diff changeset
91 # - 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
92 #
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
93 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
94 functools.partial(AlgPseudocodeLexer, no_end=True))
160
b4028838e0c8 Implement lexer option "prohibit_raiseonerror_filter".
Franz Glasner <fzglas.hg@dom66.de>
parents: 157
diff changeset
95 # 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
96 app.add_lexer("no-raiseonerror-algpseudocode",
b4028838e0c8 Implement lexer option "prohibit_raiseonerror_filter".
Franz Glasner <fzglas.hg@dom66.de>
parents: 157
diff changeset
97 functools.partial(AlgPseudocodeLexer,
b4028838e0c8 Implement lexer option "prohibit_raiseonerror_filter".
Franz Glasner <fzglas.hg@dom66.de>
parents: 157
diff changeset
98 prohibit_raiseonerror_filter=True))