[](https://github.com/SystemRDL/PeakRDL-html/actions?query=workflow%3Abuild+branch%3Amaster)
[](https://pypi.org/project/peakrdl-html)
# PeakRDL-html
Generate address space documentation HTML from compiled SystemRDL input.
For the command line tool, see the [PeakRDL project](https://peakrdl.readthedocs.io).
## Installing
Install from [PyPi](https://pypi.org/project/peakrdl-html) using pip:
python3 -m pip install peakrdl-html
## Example
An [example of HTML output](https://systemrdl.github.io/PeakRDL-html) generated from a
fictional SystemRDL register description: [turboencabulator.rdl](example/turboencabulator.rdl).
## Usage
Pass the elaborated output of the [SystemRDL Compiler](http://systemrdl-compiler.readthedocs.io)
into the exporter.
Assuming `root` is the elaborated top-level node, or an internal `AddrmapNode`:
```python
from peakrdl_html import HTMLExporter
exporter = HTMLExporter()
exporter.export(root, "path/to/output")
```
## Reference
### `HTMLExporter(**kwargs)`
Constructor for the HTML exporter class
**Optional Parameters**
* `markdown_inst`
* Override the class instance of the Markdown processor.
See the [Markdown module](https://python-markdown.github.io/reference/#Markdown)
for more details.
* By default, the following extensions are loaded: 'extra', 'admonition', 'mdx_math'
* `user_template_dir`
* Path to a directory where user-defined template overrides are stored.
* `user_static_dir`
* Path to user-defined static content to copy to output directory.
* `user_context`
* Additional context variables to load into the template namespace.
* `show_signals`
* Show signal components. Default is False
* `extra_doc_properties`
* List of properties to explicitly document.
Nodes that have a property explicitly set will show its value in a table
in the node's description. Use this to bring forward user-defined
properties, or other built-in properties in your documentation.
* `generate_source_links`
* If `True`, attempts to generate links back to original RDL source deginitions.
Defaults to `True`.
* `gitmetheurl_translators`
* Override the list of [GitMeTheURL](https://github.com/amykyta3/git-me-the-url/blob/master/README.md) translators to use when generating source links.
If unset, GitMeTheURL uses its builtin translators, as well as any installed plugins.
### `HTMLExporter.export(node, output_dir, **kwargs)`
Perform the export!
**Parameters**
* `nodes`
* Top-level node to export. Can be the top-level `RootNode` or any internal `AddrmapNode`.
Can also be a list of `RootNode` and any internal `AddrmapNode`.
* `output_dir`
* HTML output directory.
**Optional Parameters**
* `footer`
* Override footer text.
* `title`
* Override title text.
* `home_url`
* If a URL is specified, adds a home button to return to a parent home page.
* `skip_not_present`
* Control whether nodes with `ispresent=false` are generated. Default is True.
## PeakRDL TOML config options
If using the [PeakRDL command-line tool](https://peakrdl.readthedocs.io), some
additional things can be configured via the TOML configuration file.
```toml
[html]
user_template_dir = "path/to/dir/"
user_static_dir = "path/to/dir/"
extra_doc_properties = ["list", "of", "properties"]
```
Raw data
{
"_id": null,
"home_page": "https://github.com/SystemRDL/PeakRDL-html",
"name": "peakrdl-html",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "Alex Mykyta",
"author_email": "amykyta3@github.com",
"download_url": "https://files.pythonhosted.org/packages/5a/dc/1b82395b9659c70ed138444d9c2d98a802fa3b56a1288d2cf00609ce1aec/peakrdl-html-2.10.1.tar.gz",
"platform": null,
"description": "[](https://github.com/SystemRDL/PeakRDL-html/actions?query=workflow%3Abuild+branch%3Amaster)\n[](https://pypi.org/project/peakrdl-html)\n\n# PeakRDL-html\nGenerate address space documentation HTML from compiled SystemRDL input.\n\nFor the command line tool, see the [PeakRDL project](https://peakrdl.readthedocs.io).\n\n## Installing\nInstall from [PyPi](https://pypi.org/project/peakrdl-html) using pip:\n\n python3 -m pip install peakrdl-html\n\n\n## Example\n\nAn [example of HTML output](https://systemrdl.github.io/PeakRDL-html) generated from a\nfictional SystemRDL register description: [turboencabulator.rdl](example/turboencabulator.rdl).\n\n\n## Usage\nPass the elaborated output of the [SystemRDL Compiler](http://systemrdl-compiler.readthedocs.io)\ninto the exporter.\n\nAssuming `root` is the elaborated top-level node, or an internal `AddrmapNode`:\n\n```python\nfrom peakrdl_html import HTMLExporter\n\nexporter = HTMLExporter()\n\nexporter.export(root, \"path/to/output\")\n```\n\n\n## Reference\n\n### `HTMLExporter(**kwargs)`\nConstructor for the HTML exporter class\n\n**Optional Parameters**\n\n* `markdown_inst`\n * Override the class instance of the Markdown processor.\n See the [Markdown module](https://python-markdown.github.io/reference/#Markdown)\n for more details.\n * By default, the following extensions are loaded: 'extra', 'admonition', 'mdx_math'\n* `user_template_dir`\n * Path to a directory where user-defined template overrides are stored.\n* `user_static_dir`\n * Path to user-defined static content to copy to output directory.\n* `user_context`\n * Additional context variables to load into the template namespace.\n* `show_signals`\n * Show signal components. Default is False\n* `extra_doc_properties`\n * List of properties to explicitly document.\n\n Nodes that have a property explicitly set will show its value in a table\n in the node's description. Use this to bring forward user-defined\n properties, or other built-in properties in your documentation.\n* `generate_source_links`\n * If `True`, attempts to generate links back to original RDL source deginitions.\n Defaults to `True`.\n* `gitmetheurl_translators`\n * Override the list of [GitMeTheURL](https://github.com/amykyta3/git-me-the-url/blob/master/README.md) translators to use when generating source links.\n If unset, GitMeTheURL uses its builtin translators, as well as any installed plugins.\n\n\n### `HTMLExporter.export(node, output_dir, **kwargs)`\nPerform the export!\n\n**Parameters**\n\n* `nodes`\n * Top-level node to export. Can be the top-level `RootNode` or any internal `AddrmapNode`.\n Can also be a list of `RootNode` and any internal `AddrmapNode`.\n* `output_dir`\n * HTML output directory.\n\n**Optional Parameters**\n\n* `footer`\n * Override footer text.\n* `title`\n * Override title text.\n* `home_url`\n * If a URL is specified, adds a home button to return to a parent home page.\n* `skip_not_present`\n * Control whether nodes with `ispresent=false` are generated. Default is True.\n\n\n## PeakRDL TOML config options\n\nIf using the [PeakRDL command-line tool](https://peakrdl.readthedocs.io), some\nadditional things can be configured via the TOML configuration file.\n\n```toml\n[html]\nuser_template_dir = \"path/to/dir/\"\nuser_static_dir = \"path/to/dir/\"\nextra_doc_properties = [\"list\", \"of\", \"properties\"]\n```",
"bugtrack_url": null,
"license": "",
"summary": "HTML documentation generator for SystemRDL-based register models",
"version": "2.10.1",
"project_urls": {
"Homepage": "https://github.com/SystemRDL/PeakRDL-html",
"Source": "https://github.com/SystemRDL/PeakRDL-html",
"Tracker": "https://github.com/SystemRDL/PeakRDL-html/issues"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5adc1b82395b9659c70ed138444d9c2d98a802fa3b56a1288d2cf00609ce1aec",
"md5": "631f9ea1359602b54d615838354908fc",
"sha256": "955eb1c575308d35293622df3aaec26355ce8e5cdf6c88fb6a8fde216ac82f1c"
},
"downloads": -1,
"filename": "peakrdl-html-2.10.1.tar.gz",
"has_sig": false,
"md5_digest": "631f9ea1359602b54d615838354908fc",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 5586179,
"upload_time": "2023-06-02T06:19:23",
"upload_time_iso_8601": "2023-06-02T06:19:23.423462Z",
"url": "https://files.pythonhosted.org/packages/5a/dc/1b82395b9659c70ed138444d9c2d98a802fa3b56a1288d2cf00609ce1aec/peakrdl-html-2.10.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-06-02 06:19:23",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "SystemRDL",
"github_project": "PeakRDL-html",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "peakrdl-html"
}
JSON
