# Yapper
Yapper converts Python docstrings to `astro` files for use by the [Astro](https://astro.build/) static site generator.
It uses [`griffe`](https://github.com/mkdocstrings/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`](https://cityseer.benchmarkurbanism.com) documentation site and associated [docs repo](https://github.com/benchmark-urbanism/cityseer-api/tree/master/docs) 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.
```bash
yapper --config ./custom_config.toml
```
The `toml` file must include a `[tool.yapper]` section, with keys corresponding to the default configuration options:
```toml
[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:
```toml
[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.
Raw data
{
"_id": null,
"home_page": "",
"name": "yapper",
"maintainer": "",
"docs_url": null,
"requires_python": "<4.0,>=3.8",
"maintainer_email": "Gareth Simons <info@benchmarkurbanism.com>",
"keywords": "python,static-site-generator,astro,parser,documentation,docstrings",
"author": "",
"author_email": "Gareth Simons <info@benchmarkurbanism.com>",
"download_url": "https://files.pythonhosted.org/packages/84/20/dfbd9d12d16fc7ef93975595d8530fb53c53209aad8421bd23117d170b37/yapper-0.5.0.tar.gz",
"platform": null,
"description": "# Yapper\n\nYapper converts Python docstrings to `astro` files for use by the [Astro](https://astro.build/) static site generator.\n\nIt uses [`griffe`](https://github.com/mkdocstrings/griffe) to parse python modules and extracts numpy style docstrings.\n\nDocstrings and parameter descriptions will be passed through as raw markdown wrapped in Astro `<Markdown is:raw></Markdown>` components.\n\nClass and function elements are wrapped with `html` with `css` classes that can be styled from Astro.\n\n> See the [`cityseer.benchmarkurbanism.com`](https://cityseer.benchmarkurbanism.com) documentation site and associated [docs repo](https://github.com/benchmark-urbanism/cityseer-api/tree/master/docs) for a working example.\n\nConversion 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.\n\n## Configuration\n\nConfiguration 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.\n\n```bash\nyapper --config ./custom_config.toml\n```\n\nThe `toml` file must include a `[tool.yapper]` section, with keys corresponding to the default configuration options:\n\n```toml\n[tool.yapper]\npackage_root_relative_path = './'\nintro_template = \"\"\"\n---\\n\nimport { Markdown } from 'astro/components';\\n\n---\\n\n\"\"\"\noutro_template = \"\"\nmodule_map = [\n { module = \"test.mock_file\", astro = \"./tests/mock_default.astro\" },\n]\n```\n\nIf 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:\n\n```toml\n[tool.yapper]\npackage_root_relative_path = './'\nintro_template = \"\"\"\n---\\n\nimport { Markdown } from 'astro/components';\\n\nimport PageLayout from '../layouts/PageLayout.astro'\\n\n---\\n\n\\n\n<PageLayout>\n\"\"\"\noutro_template = \"\"\"\n</PageLayout>\\n\n\"\"\"\nmodule_map = [\n { module = \"test.mock_file\", py = \"./tests/mock_file.py\", astro = \"./tests/mock_default.astro\" },\n]\n```\n\nThe `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:\n\n## Development\n\n`yapper` uses a `pyproject.toml` file to specify project dependencies and scripts related to project development and publishing.\n\nSee `pyproject.toml` for available scripts.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Parser for converting python docstrings to .astro files for the Astro static site generator.",
"version": "0.5.0",
"split_keywords": [
"python",
"static-site-generator",
"astro",
"parser",
"documentation",
"docstrings"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7ab69675e738ce78a2722e2c638165f26937eb812e07a07913a7032f09e6750b",
"md5": "71b82b292c813d7bf6746222d686bbb0",
"sha256": "2bf20fceda7fd74fc85e4dfacae5dcdc8777d2bc164987f93110aaefa70592ce"
},
"downloads": -1,
"filename": "yapper-0.5.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "71b82b292c813d7bf6746222d686bbb0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.8",
"size": 10390,
"upload_time": "2023-02-04T15:46:14",
"upload_time_iso_8601": "2023-02-04T15:46:14.517022Z",
"url": "https://files.pythonhosted.org/packages/7a/b6/9675e738ce78a2722e2c638165f26937eb812e07a07913a7032f09e6750b/yapper-0.5.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8420dfbd9d12d16fc7ef93975595d8530fb53c53209aad8421bd23117d170b37",
"md5": "b7130e67d799e11d4aacb83b45c4bbcd",
"sha256": "9455a69a2d1a6417374b641ba6ccc3e66625ddf6f0cbb3979316800be948afca"
},
"downloads": -1,
"filename": "yapper-0.5.0.tar.gz",
"has_sig": false,
"md5_digest": "b7130e67d799e11d4aacb83b45c4bbcd",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.8",
"size": 17522,
"upload_time": "2023-02-04T15:46:16",
"upload_time_iso_8601": "2023-02-04T15:46:16.117682Z",
"url": "https://files.pythonhosted.org/packages/84/20/dfbd9d12d16fc7ef93975595d8530fb53c53209aad8421bd23117d170b37/yapper-0.5.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-02-04 15:46:16",
"github": false,
"gitlab": false,
"bitbucket": false,
"lcname": "yapper"
}
JSON