diff options
Diffstat (limited to 'docs/conf.py')
| -rw-r--r-- | docs/conf.py | 99 |
1 files changed, 73 insertions, 26 deletions
diff --git a/docs/conf.py b/docs/conf.py index f99f920e5..244794f0e 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -17,7 +17,7 @@ from datetime import date import sphinx # The suffix of source filenames. -source_suffix = ['.rst', '.md'] +source_suffix = ['.rst'] # The master toctree document. # inclusive-language: ignore master_doc = 'index' @@ -41,29 +41,18 @@ pygments_dark_style = 'pw_console.pigweed_code_style.PigweedCodeStyle' extensions = [ 'pw_docgen.sphinx.google_analytics', # Enables optional Google Analytics + 'pw_docgen.sphinx.kconfig', 'pw_docgen.sphinx.module_metadata', + 'pw_docgen.sphinx.pigweed_live', + 'pw_docgen.sphinx.seed_metadata', 'sphinx.ext.autodoc', # Automatic documentation for Python code 'sphinx.ext.napoleon', # Parses Google-style docstrings 'sphinxarg.ext', # Automatic documentation of Python argparse 'sphinxcontrib.mermaid', 'sphinx_design', - 'myst_parser', 'breathe', 'sphinx_copybutton', # Copy-to-clipboard button on code blocks -] - -myst_enable_extensions = [ - # "amsmath", - "colon_fence", - # "deflist", - "dollarmath", - # "html_admonition", - # "html_image", - # "linkify", - # "replacements", - # "smartquotes", - # "substitution", - # "tasklist", + 'sphinx_sitemap', ] # When a user clicks the copy-to-clipboard button the `$ ` prompt should not be @@ -124,6 +113,11 @@ html_css_files = [ "https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/all.min.css", ] +html_js_files = ['js/pigweed.js'] + +# Furo color theme variables based on: +# https://github.com/pradyunsg/furo/blob/main/src/furo/assets/styles/variables/_colors.scss +# Colors with unchanged defaults are left commented out for easy updating. html_theme_options = { 'light_css_variables': { # Make the logo text more amaranth-like @@ -160,8 +154,8 @@ html_theme_options = { 'color-sidebar-search-border': '#e815a5', 'color-sidebar-link-text--top-level': '#ff79c6', 'color-sidebar-link-text': '#8be9fd', - 'color-sidebar-item-background--current': '#575757', - 'color-sidebar-item-background--hover': '#4c333f', + 'color-sidebar-item-background--current': '#2a3037', + 'color-sidebar-item-background--hover': '#30353d', 'color-sidebar-item-expander-background--hover': '#4c333f', # Function signature colors 'color-api-function-border': '#575757', @@ -173,7 +167,8 @@ html_theme_options = { 'color-api-pre-name': '#87c1e5', # Function name 'color-api-name': '#87c1e5', - 'color-inline-code-background': '#2b2b2b', + 'color-code-background': '#2d333b', + 'color-inline-code-background': '#2d333b', 'color-inline-code-border': '#575757', 'color-text-selection-background': '#2674bf', 'color-text-selection-foreground': '#ffffff', @@ -183,16 +178,62 @@ html_theme_options = { 'color-code-hll-background': '#ffc55140', 'color-section-button': '#fb71fe', 'color-section-button-hover': '#b529aa', + # The following color changes modify Furo's default dark mode colors for + # slightly less high-contrast. + # Base Colors + # 'color-foreground-primary': '#ffffffcc', # Main text and headings + # 'color-foreground-secondary': '#9ca0a5', # Secondary text + # 'color-foreground-muted': '#81868d', # Muted text + # 'color-foreground-border': '#666666', # Content borders + 'color-background-primary': '#1c2128', # Content + 'color-background-secondary': '#22272e', # Navigation and TOC + 'color-background-hover': '#30353dff', # Navigation-item hover + 'color-background-hover--transparent': '#30353d00', + 'color-background-border': '#444c56', # UI borders + 'color-background-item': '#373e47', # "background" items (eg: copybutton) + # Announcements + # 'color-announcement-background': '#000000dd', + # 'color-announcement-text': '#eeebee', + # Brand colors + # 'color-brand-primary': '#2b8cee', + # 'color-brand-content': '#368ce2', + # Highlighted text (search) + # 'color-highlighted-background': '#083563', + # GUI Labels + # 'color-guilabel-background': '#08356380', + # 'color-guilabel-border': '#13395f80', + # API documentation + # 'color-api-keyword': 'var(--color-foreground-secondary)', + # 'color-highlight-on-target': '#333300', + # Admonitions + 'color-admonition-background': 'var(--color-background-secondary)', + # Cards + 'color-card-border': 'var(--color-background-border)', + 'color-card-background': 'var(--color-background-secondary)', + # 'color-card-marginals-background': 'var(--color-background-hover)', + # Sphinx Design cards + 'sd-color-card-background': 'var(--color-background-secondary)', + 'sd-color-card-border': 'var(--color-background-border)', }, } -mermaid_version = '9.4.0' -# TODO(tonymd): Investigate if ESM only v10 Mermaid can be used. -# This does not work: -# mermaid_init_js = ''' -# import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs'; -# mermaid.initialize({ startOnLoad: true }); -# ''' +# sphinx-sitemap needs this: +# https://sphinx-sitemap.readthedocs.io/en/latest/getting-started.html#usage +html_baseurl = 'https://pigweed.dev/' + +# https://sphinx-sitemap.readthedocs.io/en/latest/advanced-configuration.html +sitemap_url_scheme = '{link}' + +mermaid_init_js = ''' +mermaid.initialize({ + // Mermaid is manually started in //docs/_static/js/pigweed.js. + startOnLoad: false, + // sequenceDiagram Note text alignment + noteAlign: "left", + // Set mermaid theme to the current furo theme + theme: localStorage.getItem("theme") == "dark" ? "dark" : "default" +}); +''' # Output file base name for HTML help builder. htmlhelp_basename = 'Pigweeddoc' @@ -216,6 +257,7 @@ texinfo_documents = [ ), ] +templates_path = ['docs/layout'] exclude_patterns = ['docs/templates/**'] breathe_projects = { @@ -250,6 +292,11 @@ cpp_paren_attributes = [ # Disable Python type hints # autodoc_typehints = 'none' +# Break class and function signature arguments into one arg per line if the +# total length exceeds 130 characters. 130 seems about right for keeping one or +# two parameters on a single line. +maximum_signature_line_length = 130 + def do_not_skip_init(app, what, name, obj, would_skip, options): if name == "__init__": |