WIP, no APIs are "stable" in any sense
Sphinx domain to document embedded hardware SFRs.
Adds a hwreg
domain to track register descriptions and
link to them.
Install via pip:
pip install git+https://github.com/andreasWallner/sphinx-hwreg.git#<version hash that you want>
Add to your sphinx build by extending you conf.py
with:
import sphinx_hwreg
extensions = [
'sphinx_hwreg.hardware_registers',
]
To get nice visuals for the register field tables, a custom CSS needs to be added. For an example have a
look at example/register-graphic.css
. Copy this to your static html folder and add via:
html_static_path = ['_static']
html_css_files = [
'register-graphic.css',
]
A short overview for the current directives:
Generates a full listing of all registers in a module, style depending on type
.
Provide the name of the BusComponent as a parameter.
Options:
filename
path to the yaml file to load, relative to the documentation root dirtype
style to use, eitherfancy
orshort
noanchor
if present no anchors are generated - use this if the automodule is used as a second listing (e.g. in a register overview) so that links can go to a fuller description.nowarn
do not generate a warning for e.g. a register w/o and fields
Example:
.. hwreg:automodule:: PWM
:filename: _generated/pwm.yaml
:type: short
:noanchor:
:nowarn:
Short list of all registers, linking to the register description if it exists. Does not contain any information about the fields of the module.
Provide the name of the BusComponent as a parameter.
Options:
filename
path to the yaml file to load, relative to the documentation root dir
Example:
.. hwreg:automodulesummary:: PWM
:filename: _generated/pwm.yaml
Generate register field graphic and field listing for a single register.
Provide the name of the BusComponent and Register as a parameter.
Options:
filename
path to the yaml file to load, relative to the documentation root dirnoanchor
if present no anchors are generated - use this if the automodule is used as a second listing (e.g. in a register overview) so that links can go to a fuller description.
Example:
.. hwreg:autoreg:: PWM::level0
:filename: _generated/pwm.yaml
:noanchor:
To use the module for cross references only, directives and roles exist
to add registers to the hwreg
domain.
.. hwreg:define-reg:: Status (radio::status, 0x0014)
.. ext-table:: Some text...
* - :hwreg:define-bf:`TX <radio::status>`
- this is another
* - foo
- bar
This would then be a text that should also be inside the directive
Somewhere else we can link back to the register :hwreg:register:`radio::status` with it's :hwreg:bitfield:`radio::status::TX`