Skip to content
This repository was archived by the owner on Oct 24, 2025. It is now read-only.

Commit dd7ba83

Browse files
PaebbelsPaebbels
committed
Adjusted documentation configuration.
1 parent 7f7695e commit dd7ba83

File tree

1 file changed

+181
-53
lines changed

1 file changed

+181
-53
lines changed

‎doc/conf.py‎

Lines changed: 181 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -10,33 +10,170 @@
1010
# add these directories to sys.path here. If the directory is relative to the
1111
# documentation root, use os.path.abspath to make it absolute, like shown here.
1212
#
13-
import os
1413
import sys
15-
sys.path.insert(0, os.path.abspath('.'))
16-
sys.path.insert(0, os.path.abspath('..'))
17-
#sys.path.insert(0, os.path.abspath('../pyCallBy'))
18-
#sys.path.insert(0, os.path.abspath('_extensions'))
19-
#sys.path.insert(0, os.path.abspath('_themes/sphinx_rtd_theme'))
14+
from os.path import abspath
15+
from pathlib import Path
16+
from json import loads
2017

18+
sys.path.insert(0, abspath('.'))
19+
sys.path.insert(0, abspath('..'))
20+
sys.path.insert(0, abspath('../pyTooling.TerminalUI'))
21+
sys.path.insert(0, abspath('_extensions'))
22+
#sys.path.insert(0, os.path.abspath('_themes/sphinx_rtd_theme'))
2123

22-
# -- Project information -----------------------------------------------------
2324

25+
# ==============================================================================
26+
# Project information
27+
# ==============================================================================
2428
project = 'pyTooling.TerminalUI'
2529
copyright = '2007-2021, Patrick Lehmann'
2630
author = 'Patrick Lehmann'
2731

32+
# ==============================================================================
33+
# Versioning
34+
# ==============================================================================
35+
# The version info for the project you're documenting, acts as replacement for
36+
# |version| and |release|, also used in various other places throughout the
37+
# built documents.
38+
from subprocess import check_output
39+
40+
def _IsUnderGitControl():
41+
return (check_output(["git", "rev-parse", "--is-inside-work-tree"], universal_newlines=True).strip() == "true")
42+
43+
def _LatestTagName():
44+
return check_output(["git", "describe", "--abbrev=0", "--tags"], universal_newlines=True).strip()
45+
2846
# The full version, including alpha/beta/rc tags
29-
release = 'v1.5'
47+
version = "1.5" # The short X.Y version.
48+
release = "1.5.1" # The full version, including alpha/beta/rc tags.
49+
try:
50+
if _IsUnderGitControl:
51+
latestTagName = _LatestTagName()[1:] # remove prefix "v"
52+
versionParts = latestTagName.split("-")[0].split(".")
53+
54+
version = ".".join(versionParts[:2])
55+
release = latestTagName # ".".join(versionParts[:3])
56+
except:
57+
pass
58+
59+
# ==============================================================================
60+
# Miscellaneous settings
61+
# ==============================================================================
62+
# The master toctree document.
63+
master_doc = 'index'
64+
65+
# Add any paths that contain templates here, relative to this directory.
66+
templates_path = ['_templates']
67+
68+
# List of patterns, relative to source directory, that match files and
69+
# directories to ignore when looking for source files.
70+
# This pattern also affects html_static_path and html_extra_path.
71+
exclude_patterns = [
72+
"_build",
73+
"_themes",
74+
"Thumbs.db",
75+
".DS_Store"
76+
]
77+
78+
# The name of the Pygments (syntax highlighting) style to use.
79+
pygments_style = 'stata-dark'
80+
81+
82+
# ==============================================================================
83+
# Restructured Text settings
84+
# ==============================================================================
85+
prologPath = "prolog.inc"
86+
try:
87+
with open(prologPath, "r") as prologFile:
88+
rst_prolog = prologFile.read()
89+
except Exception as ex:
90+
print("[ERROR:] While reading '{0!s}'.".format(prologPath))
91+
print(ex)
92+
rst_prolog = ""
93+
94+
95+
# ==============================================================================
96+
# Options for HTML output
97+
# ==============================================================================
98+
html_theme_options = {
99+
'home_breadcrumbs': True,
100+
'vcs_pageview_mode': 'blob',
101+
}
102+
103+
html_context = {}
104+
ctx = Path(__file__).resolve().parent / 'context.json'
105+
if ctx.is_file():
106+
html_context.update(loads(ctx.open('r').read()))
107+
108+
html_theme_path = ["."]
109+
html_theme = "_theme"
110+
111+
# Add any paths that contain custom static files (such as style sheets) here,
112+
# relative to this directory. They are copied after the builtin static files,
113+
# so a file named "default.css" will overwrite the builtin "default.css".
114+
html_static_path = ['_static']
115+
116+
# Output file base name for HTML help builder.
117+
htmlhelp_basename = 'pyToolingDoc'
30118

119+
# If not None, a 'Last updated on:' timestamp is inserted at every page
120+
# bottom, using the given strftime format.
121+
# The empty string is equivalent to '%b %d, %Y'.
122+
html_last_updated_fmt = "%d.%m.%Y"
31123

32-
# -- General configuration ---------------------------------------------------
33124

34-
# Add any Sphinx extension module names here, as strings. They can be
35-
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
36-
# ones.
125+
# ==============================================================================
126+
# Options for LaTeX / PDF output
127+
# ==============================================================================
128+
from textwrap import dedent
129+
130+
latex_elements = {
131+
# The paper size ('letterpaper' or 'a4paper').
132+
'papersize': 'a4paper',
133+
134+
# The font size ('10pt', '11pt' or '12pt').
135+
#'pointsize': '10pt',
136+
137+
# Additional stuff for the LaTeX preamble.
138+
'preamble': dedent(r"""
139+
% ================================================================================
140+
% User defined additional preamble code
141+
% ================================================================================
142+
% Add more Unicode characters for pdfLaTeX.
143+
% - Alternatively, compile with XeLaTeX or LuaLaTeX.
144+
% - https://github.com/sphinx-doc/sphinx/issues/3511
145+
%
146+
\ifdefined\DeclareUnicodeCharacter
147+
\DeclareUnicodeCharacter{2265}{$\geq$}
148+
\DeclareUnicodeCharacter{21D2}{$\Rightarrow$}
149+
\fi
150+
151+
152+
% ================================================================================
153+
"""),
154+
155+
# Latex figure (float) alignment
156+
#'figure_align': 'htbp',
157+
}
158+
159+
# Grouping the document tree into LaTeX files. List of tuples
160+
# (source start file, target name, title,
161+
# author, documentclass [howto, manual, or own class]).
162+
latex_documents = [
163+
( master_doc,
164+
'pyTooling.TerminalUI.tex',
165+
'The pyTooling.TerminalUI Documentation',
166+
'Patrick Lehmann',
167+
'manual'
168+
),
169+
]
170+
171+
172+
173+
# ==============================================================================
174+
# Extensions
175+
# ==============================================================================
37176
extensions = [
38-
# Sphinx theme
39-
"sphinx_rtd_theme",
40177
# Standard Sphinx extensions
41178
"sphinx.ext.autodoc",
42179
'sphinx.ext.extlinks',
@@ -47,57 +184,39 @@
47184
'sphinx.ext.mathjax',
48185
'sphinx.ext.ifconfig',
49186
'sphinx.ext.viewcode',
50-
# 'sphinx.ext.duration',
187+
# 'sphinx.ext.duration',
51188

52-
# SphinxContrib extensions
189+
# SphinxContrib extensions
190+
# 'sphinxcontrib.actdiag',
191+
'sphinxcontrib.mermaid',
192+
# 'sphinxcontrib.seqdiag',
193+
# 'sphinxcontrib.textstyle',
194+
# 'sphinxcontrib.spelling',
195+
# 'changelog',
53196

54-
# BuildTheDocs extensions
55-
'btd.sphinx.autoprogram',
197+
# BuildTheDocs extensions
198+
# 'btd.sphinx.autoprogram',
56199
# 'btd.sphinx.graphviz',
57200
# 'btd.sphinx.inheritance_diagram',
58201

59-
# Other extensions
60-
# 'DocumentMember',
202+
# Other extensions
203+
# 'DocumentMember',
61204
'sphinx_fontawesome',
62205
'sphinx_autodoc_typehints',
63206

64-
# local extensions (patched)
207+
# local extensions (patched)
208+
# 'autoapi.sphinx',
65209

66210
# local extensions
211+
# 'DocumentMember'
67212
]
68213

69-
# Add any paths that contain templates here, relative to this directory.
70-
templates_path = ['_templates']
71-
72-
# List of patterns, relative to source directory, that match files and
73-
# directories to ignore when looking for source files.
74-
# This pattern also affects html_static_path and html_extra_path.
75-
exclude_patterns = [
76-
"_build",
77-
"Thumbs.db",
78-
".DS_Store"
79-
]
80-
81-
82-
# -- Options for HTML output -------------------------------------------------
83-
84-
# The theme to use for HTML and HTML Help pages. See the documentation for
85-
# a list of builtin themes.
86-
#
87-
# html_theme = 'alabaster'
88-
html_theme = 'sphinx_rtd_theme'
89-
90-
# Add any paths that contain custom static files (such as style sheets) here,
91-
# relative to this directory. They are copied after the builtin static files,
92-
# so a file named "default.css" will overwrite the builtin "default.css".
93-
html_static_path = ['_static']
94-
95214
# ==============================================================================
96215
# Sphinx.Ext.InterSphinx
97216
# ==============================================================================
98217
intersphinx_mapping = {
99-
'python': ('https://docs.python.org/3', None),
100-
'pyTooling': ('http://pyTooling.github.io/pyTooling', None),
218+
'python': ('https://docs.python.org/3', None),
219+
'pyTooling': ('http://pyTooling.github.io/pyTooling', None),
101220
}
102221

103222

@@ -112,10 +231,10 @@
112231
# Sphinx.Ext.ExtLinks
113232
# ==============================================================================
114233
extlinks = {
115-
'issue': ('https://github.com/pyTooling/pyTooling,TerminalUI/issues/%s', 'issue #'),
116-
'pull': ('https://github.com/pyTooling/pyTooling,TerminalUI/pull/%s', 'pull request #'),
117-
'src': ('https://github.com/pyTooling/pyTooling,TerminalUI/blob/master/pyTooling,TerminalUI/%s?ts=2', None),
118-
# 'tests': ('https://github.com/pyTooling/pyCallBy/blob/master/test/%s?ts=2', None)
234+
'issue': ('https://github.com/pyTooling/pyTooling.TerminalUI/issues/%s', 'issue #'),
235+
'pull': ('https://github.com/pyTooling/pyTooling.TerminalUI/pull/%s', 'pull request #'),
236+
'src': ('https://github.com/pyTooling/pyTooling.TerminalUI/blob/master/pyTooling/%s?ts=2', None),
237+
# 'test': ('https://github.com/pyTooling/pyTooling/blob/master/test/%s?ts=2', None)
119238
}
120239

121240

@@ -132,3 +251,12 @@
132251
# If true, `todo` and `todoList` produce output, else they produce nothing.
133252
todo_include_todos = True
134253
todo_link_only = True
254+
255+
256+
257+
# ==============================================================================
258+
# AutoAPI.Sphinx
259+
# ==============================================================================
260+
autoapi_modules = {
261+
'pyTooling.TerminalUI': {'output': "pyTooling.TerminalUI", "override": True}
262+
}

0 commit comments

Comments
 (0)