yapper

Yapper

Yapper converts Python docstrings to astro files for use by the Astro static site generator.

It uses griffe to parse python modules and extracts numpy style docstrings.

Docstrings and parameter descriptions will be passed through as raw markdown wrapped in Astro <Markdown is:raw></Markdown> components.

Class and function elements are wrapped with html with css classes that can be styled from Astro.

See the cityseer.benchmarkurbanism.com documentation site and associated docs repo for a working example.

Conversion of markdown formatting, code blocks, admonitions, etc., is all handled downstream by Astro's remark and rehype plugins. Styling is likewise handled downstream via css targeting the associated element classes.

Configuration

Configuration is provided in pyproject.toml file placed in the current directory, else a --config parameter can be provided with a relative or absolute filepath to a toml config file.

yapper --config ./custom_config.toml

The toml file must include a [tool.yapper] section, with keys corresponding to the default configuration options:

[tool.yapper]
package_root_relative_path = './'
intro_template = """
---\n
import { Markdown } from 'astro/components';\n
---\n
"""
outro_template = ""
module_map = [
  { module = "test.mock_file", astro = "./tests/mock_default.astro" },
]

If you want to wrap the .astro output in a particular layout, then set the intro_template and outro_template accordingly, for example, the following will import the PageLayout layout and will wrap the generated content accordingly:

[tool.yapper]
package_root_relative_path = './'
intro_template = """
---\n
import { Markdown } from 'astro/components';\n
import PageLayout from '../layouts/PageLayout.astro'\n
---\n
\n
<PageLayout>
"""
outro_template = """
</PageLayout>\n
"""
module_map = [
  { module = "test.mock_file", py = "./tests/mock_file.py", astro = "./tests/mock_default.astro" },
]

The module_map is mandatory and specifies the names of the python modules to be processed via the module key and an astro key corresponding to the output file:

Development

yapper uses a pyproject.toml file to specify project dependencies and scripts related to project development and publishing.

See pyproject.toml for available scripts.