mirror of
https://github.com/Akkudoktor-EOS/EOS.git
synced 2025-04-19 08:55:15 +00:00
214768795f
Use documentation generation tools that are available for Windows and Linux. Use python instead of shell scripts to generate documentation. For ReadTheDocs make generated documentation content static to avoid running scripts outside of the docs/ path which is the default path for ReadTheDOcs. Add tests that check if generated content does go out of sync with latest source. Use tabs to show commands for Windows and Linux to improve user experience. Signed-off-by: Bobby Noelte <b0661n0e17e@gmail.com>
135 lines
3.8 KiB
Python
135 lines
3.8 KiB
Python
"""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 sys
|
|
from pathlib import Path
|
|
|
|
# -- Project information -----------------------------------------------------
|
|
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
|
|
|
|
project = "Akkudoktor EOS"
|
|
copyright = "2024, Andreas Schmitz"
|
|
author = "Andreas Schmitz"
|
|
release = "0.0.1"
|
|
|
|
# -- General configuration ---------------------------------------------------
|
|
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
|
|
|
|
extensions = [
|
|
"sphinx.ext.autodoc",
|
|
"sphinx.ext.autosummary",
|
|
"sphinx.ext.napoleon",
|
|
"sphinx_rtd_theme",
|
|
"myst_parser",
|
|
"sphinx_tabs.tabs",
|
|
]
|
|
|
|
templates_path = ["_templates"]
|
|
exclude_patterns = []
|
|
|
|
source_suffix = {
|
|
".rst": "restructuredtext",
|
|
".txt": "markdown",
|
|
".md": "markdown",
|
|
}
|
|
|
|
# -- Options for Myst Markdown -----------------------------------------------
|
|
# see https://github.com/executablebooks/MyST-Parser/blob/master/docs/conf.py
|
|
|
|
myst_enable_extensions = [
|
|
"dollarmath",
|
|
"amsmath",
|
|
"deflist",
|
|
"fieldlist",
|
|
"html_admonition",
|
|
"html_image",
|
|
"colon_fence",
|
|
"smartquotes",
|
|
"replacements",
|
|
"linkify",
|
|
"strikethrough",
|
|
"substitution",
|
|
"tasklist",
|
|
"attrs_inline",
|
|
"attrs_block",
|
|
]
|
|
myst_url_schemes = {
|
|
"http": None,
|
|
"https": None,
|
|
"mailto": None,
|
|
"ftp": None,
|
|
"wiki": "https://en.wikipedia.org/wiki/{{path}}#{{fragment}}",
|
|
"doi": "https://doi.org/{{path}}",
|
|
"gh-pr": {
|
|
"url": "https://github.com/Akkudoktor-EOS/EOS/pull/{{path}}#{{fragment}}",
|
|
"title": "PR #{{path}}",
|
|
"classes": ["github"],
|
|
},
|
|
"gh-issue": {
|
|
"url": "https://github.com/Akkudoktor-EOS/EOS/issue/{{path}}#{{fragment}}",
|
|
"title": "Issue #{{path}}",
|
|
"classes": ["github"],
|
|
},
|
|
"gh-user": {
|
|
"url": "https://github.com/{{path}}",
|
|
"title": "@{{path}}",
|
|
"classes": ["github"],
|
|
},
|
|
}
|
|
myst_number_code_blocks = ["typescript"]
|
|
myst_heading_anchors = 3
|
|
myst_footnote_transition = True
|
|
myst_dmath_double_inline = True
|
|
myst_enable_checkboxes = True
|
|
myst_substitutions = {
|
|
"role": "[role](#syntax/roles)",
|
|
"directive": "[directive](#syntax/directives)",
|
|
}
|
|
|
|
# -- Options for HTML output -------------------------------------------------
|
|
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
|
|
|
|
html_theme = "sphinx_rtd_theme"
|
|
html_static_path = ["_static"]
|
|
html_logo = "_static/logo.png"
|
|
html_theme_options = {
|
|
"logo_only": False,
|
|
"titles_only": True,
|
|
}
|
|
|
|
# -- Options for autodoc -------------------------------------------------
|
|
# https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html
|
|
|
|
# Make source file directories available to sphinx
|
|
sys.path.insert(0, str(Path("..", "src").resolve()))
|
|
|
|
autodoc_default_options = {
|
|
"members": "var1, var2",
|
|
"member-order": "bysource",
|
|
"special-members": "__init__",
|
|
"undoc-members": True,
|
|
"exclude-members": "__weakref__",
|
|
}
|
|
|
|
# -- Options for autosummary -------------------------------------------------
|
|
autosummary_generate = True
|
|
|
|
# -- Options for napoleon -------------------------------------------------
|
|
napoleon_google_docstring = True
|
|
napoleon_numpy_docstring = False
|
|
napoleon_include_init_with_doc = False
|
|
napoleon_include_private_with_doc = False
|
|
napoleon_include_special_with_doc = True
|
|
napoleon_use_admonition_for_examples = False
|
|
napoleon_use_admonition_for_notes = False
|
|
napoleon_use_admonition_for_references = False
|
|
napoleon_use_ivar = False
|
|
napoleon_use_param = True
|
|
napoleon_use_rtype = True
|
|
napoleon_preprocess_types = False
|
|
napoleon_type_aliases = None
|
|
napoleon_attr_annotations = True
|