diff --git a/.github/workflows/test-suite.yml b/.github/workflows/test-suite.yml index 8004326..56affd0 100644 --- a/.github/workflows/test-suite.yml +++ b/.github/workflows/test-suite.yml @@ -14,9 +14,9 @@ jobs: name: "Python Lint" runs-on: ubuntu-latest steps: - - uses: actions/checkout@v4 + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - - uses: astral-sh/setup-uv@v3 + - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0 - name: Lint with tox run: uvx tox -e lint @@ -34,8 +34,19 @@ jobs: - macos-latest steps: - - uses: actions/checkout@v4 - - uses: astral-sh/setup-uv@v3 + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0 - name: Test with tox run: uvx tox + + docs: + name: "Python Docs" + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + + - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0 + + - name: Build docs with tox + run: uvx tox -e docs diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..6ca3550 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,97 @@ +# Configuration file for Sphinx documentation generator. +# Generated automatically by sphinx-mkdocs-migrate from plan: synthetic +import os +import sys +sys.path.insert(0, os.path.abspath('../src')) +sys.path.insert(0, os.path.abspath('..')) + +project = 'Python JSON Logger' +copyright = 'Python JSON Logger Contributors' +author = 'Documentation Authors' + +extensions = [ + 'myst_parser', + 'sphinx.ext.autodoc', + 'sphinx.ext.autosummary', + 'sphinx.ext.napoleon', + 'sphinx_copybutton', + 'sphinx_design', + 'sphinx_immaterial', +] + +source_suffix = { + '.md': 'markdown', +} + +html_theme = 'sphinx_immaterial' +html_title = 'Python JSON Logger' +html_baseurl = 'https://nhairs.github.io/python-json-logger' +autosummary_generate = False +add_module_names = False +autoclass_content = 'both' +exclude_patterns = ['.DS_Store', 'Thumbs.db', '_build'] + +html_theme_options = { 'edit_uri': 'tree/master/docs', + 'features': [ 'navigation.instant', + 'navigation.sections', + 'navigation.indexes', + 'navigation.expand', + 'navigation.top', + 'content.code.annotate', + 'content.code.copy', + 'toc.follow'], + 'globaltoc_collapse': False, + 'icon': {'logo': 'material/code-braces'}, + 'palette': [ { 'primary': 'amber', + 'scheme': 'default', + 'toggle': { 'icon': 'material/weather-night', + 'name': 'Switch to dark mode'}}, + { 'primary': 'amber', + 'scheme': 'slate', + 'toggle': { 'icon': 'material/weather-sunny', + 'name': 'Switch to light mode'}}], + 'repo_name': 'nhairs/python-json-logger', + 'repo_url': 'https://github.com/nhairs/python-json-logger', + 'site_url': 'https://nhairs.github.io/python-json-logger', + 'social': [ { 'icon': 'fontawesome/brands/github', + 'link': 'https://github.com/nhairs/python-json-logger'}], + 'version_dropdown': True, + 'version_json': 'versions.json'} + +object_description_options = [ + ('py:.*', dict(include_fields_in_toc=False)), + ('py:parameter', dict(include_in_toc=False)), +] + +myst_enable_extensions = [ + 'colon_fence', + 'deflist', +] + +myst_heading_anchors = 3 + + +import re +_re_md_link = re.compile(r'(?[^\]\n]+?)\]\((?P[^\)\s]+)\)') +_re_cross_ref = re.compile(r'(?[^\]\n]+?)\]\[(?P[a-zA-Z_0-9\.]+)\]') +_re_empty_cross_ref = re.compile(r'(?[a-zA-Z_0-9\.]+)\]\[\]') +_re_md_code = re.compile(r'(?[^`\n]+?)`(?!_|\`)') + +def process_docstrings(app, what, name, obj, options, lines): + if what == 'module' and getattr(options, 'members', None): + lines.clear() + return + for i in range(len(lines)): + if '[' in lines[i] and '][' in lines[i]: + lines[i] = _re_empty_cross_ref.sub(r':py:obj:`\g`', lines[i]) + lines[i] = _re_cross_ref.sub(r':py:obj:`\g <\g>`', lines[i]) + if '[' in lines[i] and '](' in lines[i]: + def repl(m): + clean_text = m.group('text').replace('`', '').strip() + return f'`{clean_text} <{m.group("url")}>`_' + lines[i] = _re_md_link.sub(repl, lines[i]) + if '`' in lines[i]: + lines[i] = _re_md_code.sub(r'``\g``', lines[i]) + +def setup(app): + app.connect('autodoc-process-docstring', process_docstrings) diff --git a/docs/contributing.md b/docs/contributing.md index 1994477..b23976e 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -63,8 +63,9 @@ mkdocs serve # grip ``` -!!! note - In general we will always squash merge pull requests so you do not need to worry about a "clean" commit history. +```{note} +In general we will always squash merge pull requests so you do not need to worry about a "clean" commit history. +``` ### 3. Checklist @@ -95,11 +96,11 @@ Your code will be reviewed by a maintainer. If you're not familiar with code review start by reading [this guide](https://google.github.io/eng-practices/review/). -!!! tip "Remember you are not your work" - - You might be asked to explain or justify your choices. This is not a criticism of your value as a person! +```{tip} Remember you are not your work +You might be asked to explain or justify your choices. This is not a criticism of your value as a person! - Often this is because there are multiple ways to solve the same problem and the reviewer would like to understand more about the way you solved. +Often this is because there are multiple ways to solve the same problem and the reviewer would like to understand more about the way you solved. +``` ## Common Topics diff --git a/docs/cookbook.md b/docs/cookbook.md index 06a7a7f..daed995 100644 --- a/docs/cookbook.md +++ b/docs/cookbook.md @@ -38,6 +38,7 @@ class SillyFormatter(JsonFormatter): ``` +(request-trace-ids)= ## Request / Trace IDs There are many ways to add consistent request IDs to your logging. The exact method will depend on your needs and application. @@ -211,8 +212,9 @@ ENVIRONMENT = os.environ.get('ENVIRONMENT', 'dev') By the nature of Python's logging library, the JSON formatters will only ever run in handlers which are enabled for the given log level. This saves the performance hit of constructing JSON that is never used - but what about the data we pass into the logger? There are two options available to us: using if statements to avoid the call altogether, or using lazy string evaluation libraries. -!!! note - The below strategies will work for data passed in the `msg` and `extra` arguments. +```{note} +The below strategies will work for data passed in the `msg` and `extra` arguments. +``` To avoid the logging calls we use `logger.isEnabledFor` to ensure that we only start constructing our log messages if the logger is enabled: diff --git a/docs/index.md b/docs/index.md index 4c39bfb..14025f7 100644 --- a/docs/index.md +++ b/docs/index.md @@ -19,7 +19,7 @@ This library assumes that you are famliar with the `logging` standard library pa ## Features - **Standard Library Compatible:** Implement JSON logging without modifying your existing log setup. -- **Supports Multiple JSON Encoders:** In addition to the standard libary's `json` module, also supports the [`orjson`][pythonjsonlogger.orjson], [`msgspec`][pythonjsonlogger.msgspec] JSON encoders. +- **Supports Multiple JSON Encoders:** In addition to the standard libary's `json` module, also supports the [`orjson`](reference/pythonjsonlogger/orjson.md), [`msgspec`](reference/pythonjsonlogger/msgspec.md) JSON encoders. - **Fully Customizable Output Fields:** Control required, excluded, and static fields including automatically picking up custom attributes on `LogRecord` objects. Fields can be renamed before they are output. - **Encode Any Type:** Encoders are customized to ensure that something sane is logged for any input including those that aren't supported by default. For example formatting UUID objects into their string representation and bytes objects into a base 64 encoded string. @@ -70,3 +70,16 @@ This project was originally authored by [Zakaria Zajac](https://github.com/madza It is currently maintained by: - [Nicholas Hairs](https://github.com/nhairs) - [nicholashairs.com](https://www.nicholashairs.com) + +```{toctree} +:hidden: +:maxdepth: 2 + +Home +quickstart +cookbook +changelog +security +contributing +API Reference +``` diff --git a/docs/quickstart.md b/docs/quickstart.md index 56d2de8..678eef6 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -2,10 +2,11 @@ ## Installation -!!! note - All versions of this fork use version `>=3.0.0`. +```{note} +All versions of this fork use version `>=3.0.0`. - To use pre-fork versions use `python-json-logger<3`. +To use pre-fork versions use `python-json-logger<3`. +``` ### Install via pip @@ -24,7 +25,7 @@ pip install 'python-json-logger@https://github.com/nhairs/python-json-logger/rel ## Usage -Python JSON Logger provides [`logging.Formatter`](https://docs.python.org/3/library/logging.html#logging.Formatter) classes that encode the logged message into JSON. Although [a variety of JSON encoders are supported](#alternate-json-encoders), the following examples will use the [JsonFormatter][pythonjsonlogger.json.JsonFormatter] which uses the the `json` module from the standard library. +Python JSON Logger provides [`logging.Formatter`](https://docs.python.org/3/library/logging.html#logging.Formatter) classes that encode the logged message into JSON. Although [a variety of JSON encoders are supported](#alternate-json-encoders), the following examples will use the [JsonFormatter](reference/pythonjsonlogger/json.md) which uses the the `json` module from the standard library. ### Integrating with Python's logging framework @@ -76,11 +77,13 @@ logger.info({ }) ``` -!!! warning - Be aware that if you log using a `dict`, other formatters may not be able to handle it. +```{warning} +Be aware that if you log using a `dict`, other formatters may not be able to handle it. +``` -!!! note - Your `dict` is not modified when the formatter adds fields such as `exc_info`. +```{note} +Your `dict` is not modified when the formatter adds fields such as `exc_info`. +``` You can also add additional message fields using the `extra` argument. @@ -94,7 +97,7 @@ logger.info( ) ``` -Finally, any non-standard attributes added to a `LogRecord` will also be included in the logged data. See [Cookbook: Request / Trace IDs](cookbook.md#request-trace-ids) for an example. +Finally, any non-standard attributes added to a `LogRecord` will also be included in the logged data. See [Cookbook: Request / Trace IDs](request-trace-ids) for an example. #### Default Fields @@ -155,12 +158,13 @@ def my_default(obj): formatter = JsonFormatter(json_default=my_default) ``` -!!! note - When providing your own `json_default`, you likely want to call the original `json_default` for your encoder. Python JSON Logger provides custom default serializers for each encoder that tries very hard to ensure sane output is always logged. +```{note} +When providing your own `json_default`, you likely want to call the original `json_default` for your encoder. Python JSON Logger provides custom default serializers for each encoder that tries very hard to ensure sane output is always logged. +``` ### Alternate JSON Encoders The following JSON encoders are also supported: -- [orjson](https://github.com/ijl/orjson) - [pythonjsonlogger.orjson.OrjsonFormatter][] -- [msgspec](https://github.com/jcrist/msgspec) - [pythonjsonlogger.msgspec.MsgspecFormatter][] +- [orjson](https://github.com/ijl/orjson) - [OrjsonFormatter](reference/pythonjsonlogger/orjson.md) +- [msgspec](https://github.com/jcrist/msgspec) - [MsgspecFormatter](reference/pythonjsonlogger/msgspec.md) diff --git a/docs/reference/pythonjsonlogger/core.md b/docs/reference/pythonjsonlogger/core.md new file mode 100644 index 0000000..e2e6542 --- /dev/null +++ b/docs/reference/pythonjsonlogger/core.md @@ -0,0 +1,48 @@ +# pythonjsonlogger.core + +```{eval-rst} +.. automodule:: pythonjsonlogger.core + :no-members: +``` + +```{eval-rst} +.. currentmodule:: pythonjsonlogger.core + +.. rubric:: Classes + +.. autosummary:: + :nosignatures: + + ~BaseJsonFormatter + +.. rubric:: Functions + +.. autosummary:: + :nosignatures: + + ~merge_record_extra + +.. rubric:: Attributes + +.. autosummary:: + :nosignatures: + + ~LogData + ~RESERVED_ATTRS +``` + +```{eval-rst} +.. currentmodule:: pythonjsonlogger.core + +.. autodata:: LogData + +.. autodata:: RESERVED_ATTRS + +.. autoclass:: BaseJsonFormatter + :members: + :undoc-members: + :show-inheritance: + :inherited-members: Formatter + +.. autofunction:: merge_record_extra +``` diff --git a/docs/reference/pythonjsonlogger/defaults.md b/docs/reference/pythonjsonlogger/defaults.md new file mode 100644 index 0000000..2869491 --- /dev/null +++ b/docs/reference/pythonjsonlogger/defaults.md @@ -0,0 +1,89 @@ +# pythonjsonlogger.defaults + +```{eval-rst} +.. automodule:: pythonjsonlogger.defaults + :no-members: +``` + +```{eval-rst} +.. currentmodule:: pythonjsonlogger.defaults + +.. rubric:: Functions + +.. autosummary:: + :nosignatures: + + ~bytes_default + ~dataclass_default + ~date_default + ~datetime_any + ~datetime_default + ~enum_default + ~exception_default + ~time_default + ~traceback_default + ~type_default + ~unknown_default + ~use_bytes_default + ~use_dataclass_default + ~use_date_default + ~use_datetime_any + ~use_datetime_default + ~use_enum_default + ~use_exception_default + ~use_time_default + ~use_traceback_default + ~use_type_default + ~use_uuid_default + ~uuid_default +``` + +```{eval-rst} +.. currentmodule:: pythonjsonlogger.defaults + +.. autofunction:: bytes_default + +.. autofunction:: dataclass_default + +.. autofunction:: date_default + +.. autofunction:: datetime_any + +.. autofunction:: datetime_default + +.. autofunction:: enum_default + +.. autofunction:: exception_default + +.. autofunction:: time_default + +.. autofunction:: traceback_default + +.. autofunction:: type_default + +.. autofunction:: unknown_default + +.. autofunction:: use_bytes_default + +.. autofunction:: use_dataclass_default + +.. autofunction:: use_date_default + +.. autofunction:: use_datetime_any + +.. autofunction:: use_datetime_default + +.. autofunction:: use_enum_default + +.. autofunction:: use_exception_default + +.. autofunction:: use_time_default + +.. autofunction:: use_traceback_default + +.. autofunction:: use_type_default + +.. autofunction:: use_uuid_default + +.. autofunction:: uuid_default +``` diff --git a/docs/reference/pythonjsonlogger/exception.md b/docs/reference/pythonjsonlogger/exception.md new file mode 100644 index 0000000..d5f48ac --- /dev/null +++ b/docs/reference/pythonjsonlogger/exception.md @@ -0,0 +1,34 @@ +# pythonjsonlogger.exception + +```{eval-rst} +.. automodule:: pythonjsonlogger.exception + :no-members: +``` + +```{eval-rst} +.. currentmodule:: pythonjsonlogger.exception + +.. rubric:: Classes + +.. autosummary:: + :nosignatures: + + ~MissingPackageError + ~PythonJsonLoggerError +``` + +```{eval-rst} +.. currentmodule:: pythonjsonlogger.exception + +.. autoclass:: MissingPackageError + :members: + :undoc-members: + :show-inheritance: + :inherited-members: Exception, ImportError + +.. autoclass:: PythonJsonLoggerError + :members: + :undoc-members: + :show-inheritance: + :inherited-members: Exception +``` diff --git a/docs/reference/pythonjsonlogger/index.md b/docs/reference/pythonjsonlogger/index.md new file mode 100644 index 0000000..0881190 --- /dev/null +++ b/docs/reference/pythonjsonlogger/index.md @@ -0,0 +1,15 @@ +# pythonjsonlogger + +```{toctree} +:hidden: +:maxdepth: 1 + +core +defaults +exception +json +jsonlogger +msgspec +orjson +utils +``` diff --git a/docs/reference/pythonjsonlogger/json.md b/docs/reference/pythonjsonlogger/json.md new file mode 100644 index 0000000..82d7f46 --- /dev/null +++ b/docs/reference/pythonjsonlogger/json.md @@ -0,0 +1,34 @@ +# pythonjsonlogger.json + +```{eval-rst} +.. automodule:: pythonjsonlogger.json + :no-members: +``` + +```{eval-rst} +.. currentmodule:: pythonjsonlogger.json + +.. rubric:: Classes + +.. autosummary:: + :nosignatures: + + ~JsonEncoder + ~JsonFormatter +``` + +```{eval-rst} +.. currentmodule:: pythonjsonlogger.json + +.. autoclass:: JsonEncoder + :members: + :undoc-members: + :show-inheritance: + :inherited-members: JSONEncoder + +.. autoclass:: JsonFormatter + :members: + :undoc-members: + :show-inheritance: + :inherited-members: Formatter +``` diff --git a/docs/reference/pythonjsonlogger/jsonlogger.md b/docs/reference/pythonjsonlogger/jsonlogger.md new file mode 100644 index 0000000..1559cbb --- /dev/null +++ b/docs/reference/pythonjsonlogger/jsonlogger.md @@ -0,0 +1,6 @@ +# pythonjsonlogger.jsonlogger + +```{eval-rst} +.. automodule:: pythonjsonlogger.jsonlogger + :no-members: +``` diff --git a/docs/reference/pythonjsonlogger/msgspec.md b/docs/reference/pythonjsonlogger/msgspec.md new file mode 100644 index 0000000..5ba1409 --- /dev/null +++ b/docs/reference/pythonjsonlogger/msgspec.md @@ -0,0 +1,36 @@ +# pythonjsonlogger.msgspec + +```{eval-rst} +.. automodule:: pythonjsonlogger.msgspec + :no-members: +``` + +```{eval-rst} +.. currentmodule:: pythonjsonlogger.msgspec + +.. rubric:: Classes + +.. autosummary:: + :nosignatures: + + ~MsgspecFormatter + +.. rubric:: Functions + +.. autosummary:: + :nosignatures: + + ~msgspec_default +``` + +```{eval-rst} +.. currentmodule:: pythonjsonlogger.msgspec + +.. autoclass:: MsgspecFormatter + :members: + :undoc-members: + :show-inheritance: + :inherited-members: Formatter + +.. autofunction:: msgspec_default +``` diff --git a/docs/reference/pythonjsonlogger/orjson.md b/docs/reference/pythonjsonlogger/orjson.md new file mode 100644 index 0000000..d3c5479 --- /dev/null +++ b/docs/reference/pythonjsonlogger/orjson.md @@ -0,0 +1,36 @@ +# pythonjsonlogger.orjson + +```{eval-rst} +.. automodule:: pythonjsonlogger.orjson + :no-members: +``` + +```{eval-rst} +.. currentmodule:: pythonjsonlogger.orjson + +.. rubric:: Classes + +.. autosummary:: + :nosignatures: + + ~OrjsonFormatter + +.. rubric:: Functions + +.. autosummary:: + :nosignatures: + + ~orjson_default +``` + +```{eval-rst} +.. currentmodule:: pythonjsonlogger.orjson + +.. autoclass:: OrjsonFormatter + :members: + :undoc-members: + :show-inheritance: + :inherited-members: Formatter + +.. autofunction:: orjson_default +``` diff --git a/docs/reference/pythonjsonlogger/utils.md b/docs/reference/pythonjsonlogger/utils.md new file mode 100644 index 0000000..95fc605 --- /dev/null +++ b/docs/reference/pythonjsonlogger/utils.md @@ -0,0 +1,23 @@ +# pythonjsonlogger.utils + +```{eval-rst} +.. automodule:: pythonjsonlogger.utils + :no-members: +``` + +```{eval-rst} +.. currentmodule:: pythonjsonlogger.utils + +.. rubric:: Functions + +.. autosummary:: + :nosignatures: + + ~package_is_available +``` + +```{eval-rst} +.. currentmodule:: pythonjsonlogger.utils + +.. autofunction:: package_is_available +``` diff --git a/docs/style-guide.md b/docs/style-guide.md index ab217c5..cb97b9a 100644 --- a/docs/style-guide.md +++ b/docs/style-guide.md @@ -1,3 +1,8 @@ +--- +orphan: true +--- + +(orphan)= # Python Style Guide This document outlines the coding style, conventions, and common patterns for the `python-json-logger` project. Adhering to this guide will help maintain code consistency, readability, and quality. diff --git a/mkdocs.yml b/mkdocs.yml deleted file mode 100644 index 47003c1..0000000 --- a/mkdocs.yml +++ /dev/null @@ -1,114 +0,0 @@ -site_name: "Python JSON Logger" -site_url: https://nhairs.github.io/python-json-logger -repo_url: https://github.com/nhairs/python-json-logger -edit_uri: tree/master/docs -copyright: " Copyright © Python JSON Logger Contributors" -watch: - - mkdocs.yml - - README.md - - src/pythonjsonlogger - - docs - -nav: - - "Home": index.md - - quickstart.md - - cookbook.md - - changelog.md - - security.md - - contributing.md - - API Reference: - - ... | reference/pythonjsonlogger/* - -theme: - name: material - - icon: - logo: material/code-braces - - features: - - navigation.instant - - navigation.sections - - navigation.indexes - - navigation.expand - - navigation.top - - content.code.annotate - - content.code.copy - - toc.follow - - palette: - - media: "(prefers-color-scheme: light)" - primary: amber - scheme: default - toggle: - icon: material/weather-night - name: Switch to dark mode - - media: "(prefers-color-scheme: dark)" - primary: amber - scheme: slate - toggle: - icon: material/weather-sunny - name: Switch to light mode - -extra: - social: - - icon: fontawesome/brands/github - link: https://github.com/nhairs/python-json-logger - version: - provider: mike - -markdown_extensions: - - toc: - permalink: "🔗" - - admonition - - def_list - - mdx_truly_sane_lists - - pymdownx.highlight: - anchor_linenums: true - - pymdownx.inlinehilite - - pymdownx.snippets - - pymdownx.superfences - - pymdownx.details - - pymdownx.caret - -plugins: - - autorefs - - search: - lang: en - - awesome-pages: - collapse_single_pages: true - - gen-files: - scripts: - - scripts/gen_ref_nav.py - - mkdocstrings: - default_handler: python - handlers: - python: - paths: - - src - import: - - https://docs.python.org/3/objects.inv - # - https://mkdocstrings.github.io/objects.inv - # - https://mkdocstrings.github.io/griffe/objects.inv - options: - filters: - - "!^_" - heading_level: 1 - inherited_members: true - merge_init_into_class: true - #preload_modules: [] - separate_signature: true - show_root_heading: true - show_root_full_path: true - show_signature_annotations: true - show_symbol_type_heading: true - show_symbol_type_toc: true - signature_crossrefs: true - summary: true - unwrap_annotated: true - show_source: false - docstring_section_style: spacy - - literate-nav: - nav_file: SUMMARY.txt - - mike: - canonical_version: latest - diff --git a/pyproject.toml b/pyproject.toml index fe257b4..d5cf6b8 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -56,15 +56,13 @@ dev = [ "tzdata", ## Build "build", - ## Docs - "mkdocs", - "mkdocs-material>=8.5", - "mkdocs-awesome-pages-plugin", - "mdx_truly_sane_lists", - "mkdocstrings[python]", - "mkdocs-gen-files", - "mkdocs-literate-nav", - "mike", +] +docs = [ + "Sphinx>=7.0.0", + "myst-parser>=2.0.0", + "sphinx-copybutton>=0.5.2", + "sphinx-design>=0.5.0", + "sphinx-immaterial>=0.11.0", ] [tool.setuptools.packages.find] diff --git a/scripts/gen_ref_nav.py b/scripts/gen_ref_nav.py deleted file mode 100644 index 38175e4..0000000 --- a/scripts/gen_ref_nav.py +++ /dev/null @@ -1,35 +0,0 @@ -# NOTICE: This file is from mkdocstrings-python see NOTICE for details -"""Generate the code reference pages and navigation.""" - -from pathlib import Path - -import mkdocs_gen_files - -nav = mkdocs_gen_files.Nav() -mod_symbol = '' - -for path in sorted(Path("src").rglob("*.py")): - module_path = path.relative_to("src").with_suffix("") - doc_path = path.relative_to("src").with_suffix(".md") - full_doc_path = Path("reference", doc_path) - - parts = tuple(module_path.parts) - - if parts[-1] == "__init__": - parts = parts[:-1] - doc_path = doc_path.with_name("index.md") - full_doc_path = full_doc_path.with_name("index.md") - elif parts[-1].startswith("_"): - continue - - nav_parts = [f"{mod_symbol} {part}" for part in parts] - nav[tuple(nav_parts)] = doc_path.as_posix() - - with mkdocs_gen_files.open(full_doc_path, "w") as fd: - ident = ".".join(parts) - fd.write(f"::: {ident}") - - mkdocs_gen_files.set_edit_path(full_doc_path, ".." / path) - -with mkdocs_gen_files.open("reference/SUMMARY.txt", "w") as nav_file: - nav_file.writelines(nav.build_literate_nav()) diff --git a/tox.ini b/tox.ini index 4a21c2e..99a284a 100644 --- a/tox.ini +++ b/tox.ini @@ -22,3 +22,10 @@ commands = black --check --diff src tests pylint src mypy src tests +[testenv:docs] +description = build documentation +dependency_groups = + dev + docs +commands = + sphinx-build -b html docs site/_build/html