diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..b559286 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,46 @@ +name: docs + +on: + push: + branches: + - master + tags: + - 'v[0-9]+.[0-9]+.[0-9]+' + pull_request: + branches: + - master + workflow_dispatch: + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: '0' + - uses: actions/setup-python@v5 + with: + python-version: 3.12 + - run: python3 -m pip install -U pip + - run: python3 -m pip install -r docs/requirements.txt + - run: python3 -m pip install . + - run: mkdocs build --strict -d site + env: + STAGPY_DOC_CONFIG: 1 + - uses: actions/upload-pages-artifact@v3 + with: + path: "site/" + + deploy: + needs: build + if: ${{ github.event_name == 'workflow_dispatch' || startsWith(github.ref, 'refs/tags/v') }} + permissions: + pages: write + id-token: write + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + steps: + - uses: actions/deploy-pages@v4 + id: deployment diff --git a/.readthedocs.yml b/.readthedocs.yml deleted file mode 100644 index 84b91d8..0000000 --- a/.readthedocs.yml +++ /dev/null @@ -1,19 +0,0 @@ -# Read the Docs configuration file - -version: 2 - -build: - os: ubuntu-20.04 - tools: - python: "3.9" - -sphinx: - configuration: docs/conf.py - -formats: - - pdf - -python: - install: - - requirements: docs/requirements.txt - - path: . diff --git a/LICENSE b/LICENSE index 3db6b27..4fff383 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,6 @@ MIT License -Copyright (c) 2018-2022 Adrien Morison +Copyright (c) 2018 - present Adrien Morison Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/README.rst b/README.md similarity index 50% rename from README.rst rename to README.md index e78e2c8..1500eba 100644 --- a/README.rst +++ b/README.md @@ -1,10 +1,4 @@ -.. image:: https://readthedocs.org/projects/loam/badge/?version=latest - :target: http://loam.readthedocs.io/en/latest/?badge=latest - :alt: Documentation Status - -.. image:: https://badge.fury.io/py/loam.svg - :target: https://badge.fury.io/py/loam - :alt: PyPI version +[![PyPI - Version](https://img.shields.io/pypi/v/loam)](https://pypi.org/project/loam/) loam ==== diff --git a/docs/Makefile b/docs/Makefile deleted file mode 100644 index d4bb2cb..0000000 --- a/docs/Makefile +++ /dev/null @@ -1,20 +0,0 @@ -# Minimal makefile for Sphinx documentation -# - -# You can set these variables from the command line, and also -# from the environment for the first two. -SPHINXOPTS ?= -SPHINXBUILD ?= sphinx-build -SOURCEDIR = . -BUILDDIR = _build - -# Put it first so that "make" without argument is like "make help". -help: - @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) - -.PHONY: help Makefile - -# Catch-all target: route all unknown targets to Sphinx using the new -# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). -%: Makefile - @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/conf.py b/docs/conf.py deleted file mode 100644 index b9ca5af..0000000 --- a/docs/conf.py +++ /dev/null @@ -1,98 +0,0 @@ -# Configuration file for the Sphinx documentation builder. -# -# This file only contains a selection of the most common options. For a full -# list see the documentation: -# https://www.sphinx-doc.org/en/master/usage/configuration.html - -# -- Path setup -------------------------------------------------------------- - -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. - -import os -import sys - -from pkg_resources import get_distribution - -sys.path.insert(0, os.path.abspath("..")) - -import loam - -html_theme = "sphinx_rtd_theme" - -# -- General configuration ------------------------------------------------ - -# If your documentation needs a minimal Sphinx version, state it here. -needs_sphinx = "4.0" - -# Add any Sphinx extension module names here, as strings. They can be -# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom -# ones. -extensions = [ - "sphinx.ext.autodoc", - "sphinx.ext.napoleon", -] - -root_doc = "index" - -autodoc_member_order = "bysource" -autoclass_content = "both" - -# -- Project information ----------------------------------------------------- -project = "loam" -copyright = "2018 - 2022, Adrien Morison" -author = "Adrien Morison" - -# The full version, including alpha/beta/rc tags. -release = get_distribution("loam").version -# The short X.Y version. -version = ".".join(release.split(".")[:2]) - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -exclude_patterns = ["_build"] - -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = "sphinx" - - -# -- Options for HTML output ---------------------------------------------- - -# Output file base name for HTML help builder. -htmlhelp_basename = "loamdoc" - - -# -- Options for LaTeX output --------------------------------------------- - -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, -# author, documentclass [howto, manual, or own class]). -latex_documents = [ - (root_doc, "loam.tex", "loam Documentation", "Adrien Morison", "manual"), -] - - -# -- Options for manual page output --------------------------------------- - -# One entry per manual page. List of tuples -# (source start file, name, description, authors, manual section). -man_pages = [(root_doc, "loam", "loam Documentation", [author], 1)] - - -# -- Options for Texinfo output ------------------------------------------- - -# Grouping the document tree into Texinfo files. List of tuples -# (source start file, target name, title, author, -# dir menu entry, description, category) -texinfo_documents = [ - ( - root_doc, - "loam", - "loam Documentation", - author, - "loam", - "One line description of project.", - "Miscellaneous", - ), -] diff --git a/docs/getting-started.md b/docs/getting-started.md new file mode 100644 index 0000000..b352a63 --- /dev/null +++ b/docs/getting-started.md @@ -0,0 +1,52 @@ +Getting started +=============== + + +Installation +------------ + +The loam package is available on PyPI, you can install it with pip: + +```sh title="shell" +python3 -m pip install -U loam +``` + + +Basic usage +----------- + +The following code is a very simple example showing how to use loam to create a +configuration object with no config file nor argument parsing management. + +```py +from dataclasses import dataclass +from typing import Optional + +from loam.base import entry, Section, ConfigBase + +# Dataclasses define the options and their default values. +@dataclass +class SectionA(Section): + option_a: str = "foo" + option_b: int = 42 + option_c: str = "bar" + +# You can attach metadata to each option, such as an explanation +@dataclass +class SectionB(Section): + option_d: int = entry(val=0, doc="some number") + # you can have the same option name living in two different sections + option_a: float = entry(val=3.14159, doc="some float") + +# A ConfigBase dataclass groups the sections +@dataclass +class Config(ConfigBase): + section_a: SectionA + section_b: SectionB + +conf = Config.default_() + +# You can access options value and modify them +assert conf.section_a.option_a == "foo" +conf.section_b.option_d = 3 +``` diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..925533a --- /dev/null +++ b/docs/index.md @@ -0,0 +1,3 @@ +{% + include-markdown "../README.md" +%} diff --git a/docs/index.rst b/docs/index.rst deleted file mode 100644 index 1e54402..0000000 --- a/docs/index.rst +++ /dev/null @@ -1,25 +0,0 @@ -.. loam documentation master file, created by - sphinx-quickstart on Sun Jan 28 13:32:29 2018. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - -Welcome to loam's documentation! -================================ - -.. toctree:: - :maxdepth: 2 - :caption: Getting started - - sources/firststeps - -.. toctree:: - :maxdepth: 2 - :caption: API Reference - - sources/api/base - sources/api/cli - sources/api/collections - sources/api/parsers - sources/api/tools - sources/api/error - diff --git a/docs/requirements.txt b/docs/requirements.txt index 87ebd21..c596774 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,2 +1,7 @@ -sphinx==4.3.0 -sphinx_rtd_theme==1.0.0 +mkdocs~=1.5.3 +mkdocs-gen-files~=0.5.0 +mkdocs-include-markdown-plugin~=6.0.5 +mkdocs-literate-nav~=0.6.1 +mkdocs-material~=9.5.17 +mkdocstrings[python]~=0.24.3 +black~=24.3 diff --git a/docs/sources/api/base.rst b/docs/sources/api/base.rst deleted file mode 100644 index f587365..0000000 --- a/docs/sources/api/base.rst +++ /dev/null @@ -1,5 +0,0 @@ -base -==== - -.. automodule:: loam.base - :members: diff --git a/docs/sources/api/cli.rst b/docs/sources/api/cli.rst deleted file mode 100644 index 7c34525..0000000 --- a/docs/sources/api/cli.rst +++ /dev/null @@ -1,5 +0,0 @@ -cli -=== - -.. automodule:: loam.cli - :members: diff --git a/docs/sources/api/collections.rst b/docs/sources/api/collections.rst deleted file mode 100644 index ea1af09..0000000 --- a/docs/sources/api/collections.rst +++ /dev/null @@ -1,5 +0,0 @@ -collections -=========== - -.. automodule:: loam.collections - :members: diff --git a/docs/sources/api/error.rst b/docs/sources/api/error.rst deleted file mode 100644 index 521a773..0000000 --- a/docs/sources/api/error.rst +++ /dev/null @@ -1,5 +0,0 @@ -error -===== - -.. automodule:: loam.error - :members: diff --git a/docs/sources/api/parsers.rst b/docs/sources/api/parsers.rst deleted file mode 100644 index 124ffb6..0000000 --- a/docs/sources/api/parsers.rst +++ /dev/null @@ -1,5 +0,0 @@ -parsers -======= - -.. automodule:: loam.parsers - :members: diff --git a/docs/sources/api/tools.rst b/docs/sources/api/tools.rst deleted file mode 100644 index f77bd1b..0000000 --- a/docs/sources/api/tools.rst +++ /dev/null @@ -1,5 +0,0 @@ -tools -===== - -.. automodule:: loam.tools - :members: diff --git a/docs/sources/firststeps.rst b/docs/sources/firststeps.rst deleted file mode 100644 index 41c411d..0000000 --- a/docs/sources/firststeps.rst +++ /dev/null @@ -1,49 +0,0 @@ -First steps -=========== - -Installation ------------- - -The loam package is available on PyPI, you can install it with pip:: - - python3 -m pip install -U --user loam - - -Basic usage ------------ - -The following code is a very simple example showing how to use loam to create a -configuration object with no config file nor argument parsing management. - -:: - - from dataclasses import dataclass - from typing import Optional - - from loam.base import entry, Section, ConfigBase - - # Dataclasses define the options and their default values. - @dataclass - class SectionA(Section): - option_a: str = "foo" - option_b: int = 42 - option_c: str = "bar" - - # You can attach metadata to each option, such as an explanation - @dataclass - class SectionB(Section): - option_d: int = entry(val=0, doc="some number") - # you can have the same option name living in two different sections - option_a: float = entry(val=3.14159, doc="some float") - - # A ConfigBase dataclass groups the sections - @dataclass - class Config(ConfigBase): - section_a: SectionA - section_b: SectionB - - conf = Config.default_() - - # You can access options value and modify them - assert conf.section_a.option_a == "foo" - conf.section_b.option_d = 3 diff --git a/loam/_internal.py b/loam/_internal.py index 16726ab..db5dedf 100644 --- a/loam/_internal.py +++ b/loam/_internal.py @@ -18,8 +18,8 @@ class Switch(argparse.Action): """Inherited from argparse.Action, store True/False to a +/-arg. - The :func:`switch_opt` function allows you to easily create a - :class:`~loam.tools.ConfOpt` using this action. + The `switch_opt` function allows you to easily create a + [loam.base.Entry] using this action. """ def __call__( diff --git a/loam/base.py b/loam/base.py index cb85f90..336f1b9 100644 --- a/loam/base.py +++ b/loam/base.py @@ -31,9 +31,9 @@ class Entry(Generic[T]): """Metadata of configuration options. Attributes: - val: default value. Use :attr:`val_toml` or :attr:`val_factory` instead + val: default value. Use `val_toml` or `val_factory` instead if it is mutable. - val_toml: default value as a TOML value. :attr:`from_toml` is required. + val_toml: default value as a TOML value. `from_toml` is required. The call to the latter is wrapped in a function to avoid issues if the obtained value is mutable. val_factory: default value wrapped in a function, this is useful if the @@ -46,13 +46,14 @@ class Entry(Generic[T]): implement all the cases you want to support and raise a `TypeError` in other cases. to_toml: function to cast the entry to a type that can be represented - as a TOML value. This is called when writing :class:`ConfigBase` - instances to a TOML file via :meth:`ConfigBase.to_file_`. + as a TOML value. This is called when writing + [`ConfigBase`][loam.base.ConfigBase] instances to a TOML file via + [`ConfigBase.to_file_`][loam.base.ConfigBase.to_file_]. in_file: whether the option can be set in the config file. in_cli: whether the option is a command line argument. cli_short: short version of the command line argument. cli_kwargs: keyword arguments fed to - :meth:`argparse.ArgumentParser.add_argument` during the + `argparse.ArgumentParser.add_argument` during the construction of the command line arguments parser. cli_zsh_comprule: completion rule for ZSH shell. """ @@ -70,7 +71,7 @@ class Entry(Generic[T]): cli_zsh_comprule: Optional[str] = "" def field(self) -> T: - """Produce a :class:`dataclasses.Field` from the entry.""" + """Produce a `dataclasses.Field` from the entry.""" non_none_cout = ( int(self.val is not None) + int(self.val_toml is not None) @@ -109,7 +110,7 @@ def entry( cli_kwargs: Optional[Dict[str, Any]] = None, cli_zsh_comprule: Optional[str] = "", ) -> T: - """Build Entry(...).field().""" + """Shorthand notation for `Entry(...).field()`.""" if cli_kwargs is None: cli_kwargs = {} return Entry( @@ -132,10 +133,10 @@ class Meta(Generic[T]): """Group several metadata of configuration entry. Attributes: - fld: :class:`dataclasses.Field` object from the underlying metadata. + fld: `dataclasses.Field` object from the underlying metadata. entry: the metadata from the loam API. type_hint: type hint resolved as a class. If the type hint could not - be resolved as a class, this is merely :class:`object`. + be resolved as a class, this is merely `object`. """ fld: Field[T] @@ -147,7 +148,7 @@ class Meta(Generic[T]): class Section: """Base class for a configuration section. - This implements :meth:`__post_init__`. If your subclass also implement + This implements `__post_init__`. If your subclass also implement it, please call the parent implementation. """ @@ -175,8 +176,8 @@ def meta_(self, entry_name: str) -> Meta: def cast_and_set_(self, field_name: str, value_to_cast: object) -> None: """Set an option from the string representation of the value. - This uses :meth:`Entry.from_toml` (if present) to cast the given value. - If :meth:`Entry.from_toml` is not present and the type of + This uses `Entry.from_toml` (if present) to cast the given value. + If `Entry.from_toml` is not present and the type of `value_to_cast` do not match the type hint, this calls the type hint to attempt a cast. This should only be used when setting an option to a value whose type cannot be controlled. Wherever possible, directly set diff --git a/loam/cli.py b/loam/cli.py index 8bb7335..3290c7b 100644 --- a/loam/cli.py +++ b/loam/cli.py @@ -1,4 +1,5 @@ """Definition of CLI manager.""" + from __future__ import annotations import argparse @@ -60,7 +61,7 @@ class CLIManager: """CLI manager. Args: - config_: the :class:`~loam.base.ConfigBase` holding option definitions. + config_: the [`ConfigBase`][loam.base.ConfigBase] holding option definitions. common_: special subcommand, used to define the general description of the CLI tool as well as configuration sections used by every subcommand. @@ -118,7 +119,7 @@ def sections_list(self, cmd: Optional[str] = None) -> List[str]: """List of config sections used by a command. Args: - cmd: command name, set to ``None`` or ``''`` for the bare command. + cmd: command name, set to `None` or `""` for the bare command. Returns: list of configuration sections used by that command. @@ -207,11 +208,10 @@ def parse_args(self, arglist: Optional[List[str]] = None) -> Namespace: Args: arglist: list of arguments to parse. If set to None, - ``sys.argv[1:]`` is used. + `sys.argv[1:]` is used. Returns: - the argument namespace returned by the - :class:`argparse.ArgumentParser`. + the argument namespace returned by the `argparse.ArgumentParser`. """ args = self._parser.parse_args(args=arglist) sub_cmd = args.loam_sub_name @@ -294,7 +294,7 @@ def zsh_complete( cmd: command name that should be completed. cmds: extra command names that should be completed. sourceable: if True, the generated file will contain an explicit - call to ``compdef``, which means it can be sourced to activate + call to `compdef`, which means it can be sourced to activate CLI completion. force_grouping: if True, assume zsh supports grouping of options. Otherwise, loam will attempt to check whether zsh >= 5.4. diff --git a/loam/collections.py b/loam/collections.py index e4a8146..c9b0bd2 100644 --- a/loam/collections.py +++ b/loam/collections.py @@ -13,17 +13,17 @@ @dataclass(frozen=True) class TupleEntry(Generic[T]): - """Represent a tuple[T, ...] entry. + """Represent a `tuple[T, ...]` entry. It is able to: - - parse a TOML array [elt_a, elt_b, elt_c] into a tuple[T, ...] by feeding - each element to :attr:`inner_from_toml`. - - parse a string into a tuple[T, ...] by splitting the string with - :attr:`str_sep`, stripping each substrings, and feeding those to - :attr:`inner_from_toml` (which therefore should be able to parse strings - into T). Set :attr:`str_sep` to "" to split on whitespaces, and set it to - None to raise a TypeError when attempting to parse a string into a tuple. + - parse a TOML array `[elt_a, elt_b, elt_c]` into a `tuple[T, ...]` by feeding + each element to `inner_from_toml`. + - parse a string into a `tuple[T, ...]` by splitting the string with + `str_sep`, stripping each substrings, and feeding those to + `inner_from_toml` (which therefore should be able to parse strings + into `T`). Set `str_sep` to `""` to split on whitespaces, and set it to + `None` to raise a TypeError when attempting to parse a string into a tuple. - dump the tuple as a TOML array using `inner_to_toml` to convert each element into a type with a TOML representation. @@ -59,9 +59,9 @@ def entry( cli_short: Optional[str] = None, cli_zsh_comprule: Optional[str] = "", ) -> Tuple[T, ...]: - """Produce a :class:`dataclasses.Field` with desired options. + """Produce a `dataclasses.Field` with desired options. - See :class:`~loam.base.Entry` for an explanation on the parameters. + See [`Entry`][loam.base.Entry] for an explanation on the parameters. """ return Entry( val=self.from_toml(default), @@ -96,7 +96,7 @@ def to_toml(self, val: Tuple[T, ...]) -> Tuple[object, ...]: @dataclass class MaybeEntry(Generic[T]): - """Represent an Optional[T] entry.""" + """Represent an `Optional[T]` entry.""" inner_from_toml: Callable[[Any], T] inner_to_toml: Optional[Callable[[T], object]] = None @@ -111,9 +111,9 @@ def entry( cli_short: Optional[str] = None, cli_zsh_comprule: Optional[str] = "", ) -> Optional[T]: - """Produce a :class:`dataclasses.Field` with desired options. + """Produce a `dataclasses.Field` with desired options. - See :class:`~loam.base.Entry` for an explanation on the parameters. + See [`Entry`][loam.base.Entry] for an explanation on the parameters. """ return Entry( val_factory=lambda: self.from_toml(default), @@ -128,7 +128,7 @@ def entry( ).field() def from_toml(self, obj: object) -> Optional[T]: - """Build an Optional[T] from a TOML object.""" + """Build an `Optional[T]` from a TOML object.""" if obj is None or self.none_to_toml == obj: return None return self.inner_from_toml(obj) diff --git a/loam/parsers.py b/loam/parsers.py index 41049ee..8a8c6b9 100644 --- a/loam/parsers.py +++ b/loam/parsers.py @@ -1,6 +1,6 @@ """Parsers for your CLI arguments. -These functions can be used as `from_toml` in :attr:`~loam.base.Entry`. +These functions can be used as `from_toml` in [`Entry`][loam.base.Entry]. """ from __future__ import annotations @@ -11,10 +11,10 @@ def strict_slice_parser(arg: object) -> slice: """Parse a string into a slice. - Note that this errors out on a single integer with no `:`. If you - want to treat a single integer as a slice from 0 to that value, see - :func:`slice_parser`. To treat a single integer as an integer, see - :func:`slice_or_int`. + Note that this errors out on a single integer with no `:`. If you want to + treat a single integer as a slice from 0 to that value, see + [`slice_parser`][loam.parsers.slice_parser]. To treat a single integer as an + integer, see [`slice_or_int_parser`][loam.parsers.slice_or_int_parser]. """ soi = slice_or_int_parser(arg) if isinstance(soi, int): @@ -25,9 +25,10 @@ def strict_slice_parser(arg: object) -> slice: def slice_parser(arg: object) -> slice: """Parse a string into a slice. - Note that this treats a single integer as a slice from 0 to that - value. To error out on a single integer, use :func:`strict_slice_parser`. - To parse it as an integer, use :func:`slice_or_int_parser`. + Note that this treats a single integer as a slice from 0 to that value. To + error out on a single integer, use + [`strict_slice_parser`][loam.parsers.strict_slice_parser]. To parse it as an + integer, use [`slice_or_int_parser`][loam.parsers.slice_or_int_parser]. """ soi = slice_or_int_parser(arg) if isinstance(soi, int): @@ -38,9 +39,9 @@ def slice_parser(arg: object) -> slice: def slice_or_int_parser(arg: object) -> Union[slice, int]: """Parse a string into a slice. - Note that this treats a single integer as an integer value. To error out - on a single integer, use :func:`strict_slice_parser`. To parse it as a - slice, use :func:`slice_parser`. + Note that this treats a single integer as an integer value. To error out on + a single integer, use [`strict_slice_parser`][loam.parsers.strict_slice_parser]. + To parse it as a slice, use [`slice_parser`][loam.parsers.slice_parser]. """ if isinstance(arg, int): return arg diff --git a/loam/tools.py b/loam/tools.py index 8797803..b302ab9 100644 --- a/loam/tools.py +++ b/loam/tools.py @@ -24,7 +24,7 @@ def path_entry( ) -> Path: """Define a path option. - This creates a path option. See :class:`loam.base.Entry` for the meaning of + This creates a path option. See [`Entry`][loam.base.Entry] for the meaning of the arguments. By default, the zsh completion rule completes any file. You can switch this to only directories with the `cli_zsh_only_dirs` option, or set your own completion rule with `cli_zsh_comprule`. @@ -50,12 +50,12 @@ def switch_opt(default: bool, shortname: Optional[str], doc: str) -> bool: """Define a switchable option. This creates a boolean option. If you use it in your CLI, it can be - switched on and off by prepending + or - to its name: +opt / -opt. + switched on and off by prepending `+` or `-` to its name: `+opt` / `-opt`. Args: default: the default value of the swith option. shortname: short name of the option, no shortname will be used if set - to None. + to `None`. doc: short description of the option. """ return Entry( @@ -70,10 +70,10 @@ def switch_opt(default: bool, shortname: Optional[str], doc: str) -> bool: def command_flag(doc: str, shortname: Optional[str] = None) -> bool: """Define a command line flag. - The corresponding option is set to true if it is passed as a command line - option. This is similar to :func:`switch_opt`, except the option is not - available from config files. There is therefore no need for a mechanism to - switch it off from the command line. + The corresponding option is set to `True` if it is passed as a command line + option. This is similar to [`switch_opt`][loam.tools.switch_opt], except the + option is not available from config files. There is therefore no need for a + mechanism to switch it off from the command line. Args: doc: short description of the option. diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..4a5c245 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,70 @@ +site_name: loam +repo_url: https://github.com/amorison/loam +repo_name: amorison/loam +copyright: "© 2018 - present, Adrien Morison" + +validation: + omitted_files: warn + absolute_links: warn + unrecognized_links: warn + +nav: + - Home: + - index.md + - getting-started.md + - API Reference: reference/ + +watch: + - loam + +plugins: + - search + - include-markdown + - gen-files: + scripts: + - scripts/gen_ref_pages.py + - literate-nav: + nav_file: SUMMARY.md + - mkdocstrings: + handlers: + python: + options: + members_order: source + show_source: false + show_signature_annotations: true + separate_signature: true + +markdown_extensions: + - pymdownx.highlight: + anchor_linenums: true + line_spans: __span + pygments_lang_class: true + - pymdownx.superfences + +theme: + name: material + features: + - content.code.copy + - navigation.indexes + - navigation.tabs + - search.suggest + palette: + # Palette toggle for automatic mode + - media: "(prefers-color-scheme)" + toggle: + icon: material/brightness-auto + name: Switch to light mode + # Palette toggle for light mode + - media: "(prefers-color-scheme: light)" + scheme: default + toggle: + icon: material/brightness-7 + name: Switch to dark mode + # Palette toggle for dark mode + - media: "(prefers-color-scheme: dark)" + scheme: slate + toggle: + icon: material/brightness-4 + name: Switch to system preference + icon: + repo: fontawesome/brands/github diff --git a/scripts/gen_ref_pages.py b/scripts/gen_ref_pages.py new file mode 100644 index 0000000..bb00fd2 --- /dev/null +++ b/scripts/gen_ref_pages.py @@ -0,0 +1,33 @@ +"""Generate API reference documentation.""" + +from pathlib import Path + +import mkdocs_gen_files + +nav = mkdocs_gen_files.Nav() + +root = Path(__file__).parent.parent +src = root + +for path in sorted((src / "loam").rglob("*.py")): + module_path = path.relative_to(src).with_suffix("") + doc_path = module_path.with_suffix(".md") + + parts = module_path.parts + + if parts[-1] == "__init__": + parts = parts[:-1] + doc_path = doc_path.with_stem("index") + + if any(p.startswith("_") for p in parts): + continue + + nav[parts] = doc_path.as_posix() + + full_doc_path = Path("reference", doc_path) + with mkdocs_gen_files.open(full_doc_path, "w") as fd: + identifier = ".".join(parts) + print("::: " + identifier, file=fd) + +with mkdocs_gen_files.open("reference/SUMMARY.md", "w") as nav_file: + nav_file.writelines(nav.build_literate_nav())