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
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
|
# Configuration file for the Sphinx documentation builder.
#
# For the full list of built-in configuration values, see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html
import os, sys
from pathlib import Path
# from rinoh.frontend.rst import ReStructuredTextReader
# from rinoh.template import TemplateConfigurationFile
# the parser builds a rinohtype document tree
# parser = ReStructuredTextReader()
# with open('index.rst') as file:
# document_tree = parser.parse(file)
# load the article template configuration file
# script_path = Path(sys.path[0]).resolve()
# config = TemplateConfigurationFile(script_path / 'oneroll.rtt')
# render the document to 'my_document.pdf'
# document = config.document(document_tree)
# document.render('my_document')
# rinoh_documents = [dict(doc='index', # top-level file (index.rst)
# target='manual')] # output file (manual.pdf)
if sys.version_info >= (3, 11):
import tomllib
else:
import tomli as tomllib
def setup(app):
app.add_config_value("releaselevel", "", "env")
DATA = None
PYPROJECT = os.path.join("..", "..", "Cargo.toml")
with open(PYPROJECT, "r", encoding="utf8") as f:
pyproject = f.read()
DATA = tomllib.loads(pyproject)
PROJECT_VERSION = DATA["package"]["version"]
PROJECT_NAME = DATA["package"]["name"]
AUTHOR_TABLE = DATA["package"]["authors"]
AUTHORS = ",".join([f"{aut}" for aut in AUTHOR_TABLE])
# -- Project information -----------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
project = "OneRoll" # PROJECT_NAME
release = PROJECT_VERSION # "latest"
copyright = "2023-PRESENT, HydroRoll-Team."
author = AUTHORS # "Hsiang Nianian"
# html_title = "HydroRoll Docs"
# -- General configuration ---------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
extensions = [
"sphinx.ext.autodoc",
"sphinx.ext.autosectionlabel",
"sphinx.ext.coverage",
"sphinx.ext.doctest",
"sphinx.ext.viewcode",
"sphinx.ext.todo",
"sphinx.ext.napoleon",
"sphinx.ext.autosummary",
"sphinx.ext.extlinks",
"sphinx.ext.graphviz",
"sphinx.ext.inheritance_diagram",
"sphinx.ext.imgmath",
"sphinx.ext.intersphinx",
"sphinxcontrib.httpdomain",
"sphinx.ext.ifconfig",
"myst_parser",
"sphinx_click",
]
doctest_global_setup = """
try:
import hydro_roll as hr
import hydro_roll_core as hrc
except ImportError:
hr = None
hrc = None
"""
todo_include_todos = True
todo_emit_warnings = True
intersphinx_mapping = {"python": ("https://docs.python.org/3", None)}
templates_path = ["_templates"]
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
extlinks = {
"issue": ("https://github.com/HydroRoll-Team/HydroRoll/issues/%s", "[issue %s]"),
}
source_suffix = {
".rst": "restructuredtext",
".txt": "markdown",
".md": "markdown",
}
rst_prolog = """
.. ifconfig:: releaselevel in ('alpha', 'beta', 'rc')
.. warning::
This stuff is only included in the built docs for unstable versions.
"""
rst_epilog = """
.. |psf| replace:: Python Software Foundation
"""
# locale_dirs = ["../locales/"] # path is example but recommended.
# gettext_compact = False # optional.
# gettext_uuid = True # optional.
numfig = True # Figures, tables and code blocks are automatically numbered if they have a title
pygments_style = "rrt" # default sphinx, change the style of code block
math_number_all = True # Number all equations, figures, tables and code blocks
# html_additional_pages = {
# "copy": "copying.html",
# }
html_split_index = True # Split the index page by each alphabet
# -- Options for HTML output -------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
html_theme = "furo"
html_static_path = ["../_static"]
_html_logo = (
"https://cdn.jsdelivr.net/gh/HydroRoll-Team/HydroRoll@main/docs/_static/logo.png"
)
# html_logo = _html_logo
html_favicon = _html_logo
html_css_files = [
"https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.0.0/css/fontawesome.min.css",
"https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.0.0/css/brands.min.css",
]
html_copy_source = True
html_show_sourcelink = True
html_theme_options = {
"announcement": "<em><a href='#'>documentation</a> is still under construction now, welcome any <a href='contributing.html'>contribution</a>!</em>",
"source_repository": "https://github.com/HydroRoll-Team/HydroRoll/",
"source_branch": "main",
"source_directory": "docs/source/",
# Toc options
# "collapse_navigation": True,
# "sticky_navigation": False,
# "navigation_depth": 1,
# "includehidden": False,
# "titles_only": True,
"footer_icons": [
{
"name": "GitHub",
"url": "https://github.com/HydroRoll-Team/HydroRoll/",
"html": "",
"class": "fa-brands fa-github",
},
{
"name": "Pypi",
"url": "https://pypi.org/project/hydro_roll/",
"html": "",
"class": "fa-brands fa-python",
},
],
}
# html_sidebars = {
# '**': ['globaltoc.html', 'sourcelink.html', 'searchbox.html', 'relations.html'],
# 'using/windows': ['windowssidebar.html', 'searchbox.html'],
# }
latex_documents = {}
|