1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
|
- """
- An opinionated sphinx setup for academic or scientific reports in Sphinx.
- Sphinx Documentation: https://www.sphinx-doc.org/en/master/usage/configuration.html
- """
- import re
- from datetime import datetime
- from dynaconf import settings
- # -- Project Information ------
- import os
- import sys
- # Autodoc!
- sys.path.insert(0, os.path.abspath('..'))
- # Project or Documentation Title
- project = settings.get("project_title", "My Project")
- project_slug = re.sub("([^a-zA-Z0-9])+", "-", project).lower()
- # TODO: Handle Multiple Authors
- author = settings.get("author", "")
- # Academic Work should not be copy righted
- copyright = settings.get("copyright", "") or f"{datetime.today().year}, {author}"
- # -- Document Settings ------
- # Index Document (excluding suffix)
- master_doc = "index"
- # Files to ignore
- exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
- # Parsers for source file extensions
- source_suffix = {
- '.rst': 'restructuredtext',
- '.md': 'markdown',
- }
- # Template Paths
- templates_path = ["templates"]
- # -- Extensions -----
- extensions = [
- # Autodoc
- "sphinx.ext.autodoc",
-
- # TODOs for WIP Docs
- "sphinx.ext.todo",
- # Render LaTeX for HTML outputs
- "sphinx.ext.mathjax",
- # Configuration-driven Content
- "sphinx.ext.ifconfig",
- # Add Code Documentation if there is associated code
- "sphinx.ext.viewcode",
- # Embed Jupyter Notebooks
- "nbsphinx",
- # PlantUML driven Diagrams
- "sphinx.ext.graphviz",
- "sphinxcontrib.plantuml",
- "sphinx.ext.napoleon",
- # Citations and Reference Management
- "sphinxcontrib.bibtex",
- # Markdown Support
- "recommonmark",
-
- ]
- # TODO: Add in other extensions in the toml file
- # Pseudo-code:
- extensions.extend(filter(lambda ext: ext not in extensions, settings.get("extensions")))
- # -- Figure and Caption Settings -----
- # See: https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-numfig
- numfig = True
- # -- LaTeX Settings -----
- # See: https://www.sphinx-doc.org/en/master/latex.html
- # See: https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-latex_documents
- _targetname = f"{project_slug}.tex"
- latex_documents = [
- (master_doc, _targetname, project, author, "howto")
- ]
- latex_logo = settings.get("logo", None)
- if settings.get("printed", False):
- latex_show_pagerefs = True
- latex_show_urls = "footnote"
- _latex_preamble = r"""
- \usepackage{booktabs}
- % See: https://sphinxcontrib-bibtex.readthedocs.io/en/latest/usage.html
- % make phantomsection empty inside figures
- \usepackage{etoolbox}
- \AtBeginEnvironment{figure}{\renewcommand{\phantomsection}{}}
- """
- # See: https://www.sphinx-doc.org/en/master/latex.html#the-latex-elements-configuration-setting
- latex_elements = {
- "figure_align": "H",
- "preamble": _latex_preamble,
- }
- # -- HTML Settings -----
- html_theme = "haiku"
- html_static_path = ["static"]
- html_theme_options = {
- # Disable showing the sidebar. Defaults to 'false'
- "nosidebar": True,
- "relbarbgcolor": "black"
- }
- # -- TODOS Settings -----
- todo_include_todos = True
|