Skip to content

Commit 93b7df2

Browse files
amykyta3amykyta3
committed
Fill in docs. Prep for release
1 parent 750ed0a commit 93b7df2

File tree

18 files changed

+813
-58
lines changed

18 files changed

+813
-58
lines changed

‎.github/workflows/build.yml‎

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
name: build
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
- 'dev/**'
8+
pull_request:
9+
branches: [ main ]
10+
release:
11+
types:
12+
- published
13+
14+
# Allows you to run this workflow manually from the Actions tab
15+
workflow_dispatch:
16+
17+
jobs:
18+
test:
19+
strategy:
20+
matrix:
21+
python-version:
22+
- "3.7"
23+
- "3.8"
24+
- "3.9"
25+
- "3.10"
26+
- "3.11"
27+
- "3.12"
28+
- "3.13"
29+
include:
30+
- os: ubuntu-latest
31+
32+
# older versions need older OS
33+
- python-version: "3.7"
34+
os: ubuntu-22.04
35+
36+
- python-version: "3.8"
37+
os: ubuntu-22.04
38+
39+
runs-on: ${{ matrix.os }}
40+
41+
steps:
42+
- uses: actions/checkout@v3
43+
44+
- name: Set up Python ${{ matrix.python-version }}
45+
uses: actions/setup-python@v4
46+
with:
47+
python-version: ${{ matrix.python-version }}
48+
49+
- name: Install dependencies
50+
run: |
51+
python -m pip install -r docs/requirements.txt
52+
53+
- name: Install
54+
run: |
55+
python -m pip install "."
56+
57+
- name: Test
58+
run: |
59+
cd docs
60+
make clean html
61+
62+
#-------------------------------------------------------------------------------
63+
build:
64+
needs:
65+
- test
66+
name: Build distributions
67+
runs-on: ubuntu-latest
68+
steps:
69+
- uses: actions/checkout@v3
70+
71+
- uses: actions/setup-python@v4
72+
name: Install Python
73+
with:
74+
python-version: "3.12"
75+
76+
- name: Install dependencies
77+
run: |
78+
python -m pip install build
79+
80+
- name: Build sdist
81+
run: python -m build
82+
83+
- uses: actions/upload-artifact@v4
84+
with:
85+
name: dist
86+
path: |
87+
dist/*.tar.gz
88+
dist/*.whl
89+
90+
#-------------------------------------------------------------------------------
91+
deploy:
92+
needs:
93+
- build
94+
95+
runs-on: ubuntu-latest
96+
environment: release
97+
permissions:
98+
id-token: write
99+
100+
# Only publish when a GitHub Release is created.
101+
if: github.event_name == 'release'
102+
steps:
103+
- uses: actions/download-artifact@v4
104+
with:
105+
name: dist
106+
path: dist
107+
108+
- uses: pypa/gh-action-pypi-publish@release/v1

‎README.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
[![Documentation Status](https://readthedocs.org/projects/sphinx-peakrdl/badge/?version=latest)](http://sphinx-peakrdl.readthedocs.io)
2+
[![build](https://github.com/SystemRDL/PeakRDL/workflows/build/badge.svg)](https://github.com/SystemRDL/sphinx-peakrdl/actions?query=workflow%3Abuild+branch%3Amain)
3+
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/sphinx-peakrdl.svg)](https://pypi.org/project/sphinx-peakrdl)
4+
15
# PeakRDL integration for Sphinx-Doc
26

3-
Coming soon!
7+
See the [Sphinx-PeakRDL Documentation](http://sphinx-peakrdl.readthedocs.io) for more details.

‎docs/conf.py‎

Lines changed: 22 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,12 @@
66
# -- Project information -----------------------------------------------------
77
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
88

9-
project = 'PeakRDL Extension for SphinxDocs'
10-
copyright = '2025, Alex Mykyta'
9+
import datetime
10+
11+
project = 'PeakRDL Extension for Sphinx-Doc'
12+
copyright = '%d, Alex Mykyta' % datetime.datetime.now().year
1113
author = 'Alex Mykyta'
14+
html_title = project
1215

1316
# -- General configuration ---------------------------------------------------
1417
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
@@ -27,11 +30,25 @@
2730
# -- Options for HTML output -------------------------------------------------
2831
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
2932

30-
#html_theme = 'sphinx_rtd_theme'
31-
#html_theme = 'alabaster'
3233
html_theme = "sphinx_book_theme"
34+
html_theme_options = {
35+
"repository_url": "https://github.com/SystemRDL/sphinx-peakrdl",
36+
"path_to_docs": "docs",
37+
"use_download_button": False,
38+
"use_source_button": True,
39+
"use_repository_button": True,
40+
"use_issues_button": True,
41+
"announcement": (
42+
"⚠️ This extension is still in early development. "
43+
"If you have ideas on what could be improved, let me know! ⚠️"
44+
),
45+
}
3346
html_static_path = []
3447

48+
# -- PeakRDL config ------------------------------------------------------------
3549
peakrdl_input_files = [
36-
"rdl_src/turboencabulator.rdl"
50+
"rdl_src/uart.rdl",
51+
"rdl_src/turboencabulator.rdl",
52+
"rdl_src/thingamabob.rdl",
53+
"rdl_src/my_soc_top.rdl",
3754
]

‎docs/configuring.rst‎

Lines changed: 139 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
Configuring
2+
===========
3+
4+
.. role:: code-py(code)
5+
:language: Python
6+
7+
.. note::
8+
Unless specified otherwise, all relative file paths used in config options
9+
are interpreted as relative to the enclosing ``conf.py``.
10+
11+
12+
13+
PeakRDL compilation settings
14+
----------------------------
15+
16+
.. confval:: peakrdl_cfg_toml
17+
:type: :code-py:`str`
18+
19+
Optional path to a PeakRDL configuration TOML file.
20+
This is equivalent to the ``peakrdl`` command-line tool's ``--peakrdl-cfg`` flag.
21+
22+
If not specified, a PeakRDL TOML config file is discovered using the
23+
`same rules as the command-line tool <https://peakrdl.readthedocs.io/en/latest/configuring.html>`_.
24+
25+
26+
.. confval:: peakrdl_input_files
27+
:type: :code-py:`list[str]`
28+
29+
List of input files to process. Files shall be listed in dependency-order to
30+
ensure child components declared before instantiated.
31+
32+
33+
.. confval:: peakrdl_incdirs
34+
:type: :code-py:`list[str]`
35+
36+
List of additional include search paths.
37+
38+
39+
.. confval:: peakrdl_parameters
40+
:type: :code-py:`dict[str, Any]`
41+
42+
Dictionary of parameters to pass to the top-level component when elaborating.
43+
44+
Example:
45+
46+
.. code-block:: python
47+
48+
peakrdl_parameters = {
49+
"N_CHANNELS": 16,
50+
"BLOCK_VERSION_STR": "v1.2.3",
51+
}
52+
53+
54+
.. confval:: peakrdl_defines
55+
:type: :code-py:`dict[str, str|None]`
56+
57+
Dictionary of verilog-style define macros to inject into the SystemRDL
58+
preprocesor namespace.
59+
60+
Assigning a macro :code-py:`None` is acceptable if novalue is needed.
61+
62+
Example:
63+
64+
.. code-block:: python
65+
66+
peakrdl_defines = {
67+
"FOO": "asdf",
68+
"BAR": None,
69+
}
70+
71+
72+
.. confval:: peakrdl_top_component
73+
:type: :code-py:`str`
74+
75+
Explicitly choose which addrmap in the root namespace will be the top-level
76+
component. If unset, The last addrmap defined will be chosen.
77+
78+
79+
80+
Cross-reference settings
81+
------------------------
82+
83+
.. confval:: peakrdl_default_link_to
84+
:type: :code-py:`str`
85+
:default: :code-py:`"html"`
86+
87+
Configures what the default behavior is for register map cross-references.
88+
If not explicitly specified, behavior is determined by this setting.
89+
90+
"html"
91+
Link to PeakRDL-HTML output
92+
"doc"
93+
Link to an inline documentation reference generated by either the
94+
:rst:dir:`rdl:docnode` or :rst:dir:`rdl:doctree` directives.
95+
96+
.. note::
97+
If "doc" is selected, but a corresponding target node was never inserted
98+
using :rst:dir:`rdl:docnode` or :rst:dir:`rdl:doctree`, the reference
99+
will attempt to link to the PeakRDL html output if available.
100+
101+
102+
103+
PeakRDL-HTML output settings
104+
----------------------------
105+
.. confval:: peakrdl_html_enable
106+
:type: :code-py:`str`
107+
:default: :code-py:`True`
108+
109+
.. confval:: peakrdl_html_title
110+
:type: :code-py:`str`
111+
112+
Override the title text for the PeakRDL-HTML output.
113+
114+
.. confval:: peakrdl_html_extra_doc_properties
115+
:type: :code-py:`list[str]`
116+
117+
List of additional properties to explicitly document.
118+
119+
Nodes that have a property explicitly set will show its value in a table in
120+
the node's description. Use this to bring forward user-defined properties,
121+
or other built-in properties in your documentation.
122+
123+
124+
125+
Inline docnode/doctree settings
126+
-------------------------------
127+
128+
.. confval:: peakrdl_doc_wrap_section
129+
:type: :code-py:`bool`
130+
:default: :code-py:`True`
131+
132+
Whether to wrap :rst:dir:`rdl:docnode` output in a section heading.
133+
134+
Configures the default behavior for all :rst:dir:`rdl:docnode` directives.
135+
If not explicitly specified, behavior is determined by this setting.
136+
137+
.. note::
138+
Cross-references will not be able to link to a :rst:dir:`rdl:docnode` if
139+
it is not wrapped in a section heading.

‎docs/cross-references.rst‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
Cross-references
2+
================
3+
4+
.. role:: code-rst(code)
5+
:language: reStructuredText
6+
7+
.. rst:directive:: .. rdl:relative-to:: path
8+
9+
It can be cumbersome to always specify the full register hierarchy in your docs.
10+
This directive lets you temporarily set a more localized scope to a hierarchy
11+
to make following references in the same document easier to manage.
12+
13+
.. code-block:: rst
14+
15+
Annoying! :rdl:ref:`very.long.path.to.my_block.my_register`
16+
17+
.. rdl:relative-to:: very.long.path.to
18+
19+
Much better! :rdl:ref:`my_block.my_register`
20+
21+
22+
Cross-references will first search relative to the path specified, then
23+
fall back to searching the absolute path.
24+
25+
26+
27+
28+
29+
.. rst:role:: rdl:ref
30+
31+
Insert an inline cross-reference link to an existing register reference node.
32+
33+
The contents of the link text can be controlled in several ways:
34+
35+
* :code-rst:`:rdl:ref:\`path.to.my_block.my_register\`` Results in the full link text: ``path.to.my_block.my_register``
36+
* :code-rst:`:rdl:ref:\`~path.to.my_block.my_register\`` Truncates text to only show the last segment: ``my_register``
37+
* :code-rst:`:rdl:ref:\`path.to.|my_block.my_register\`` Truncates everything before the ``|``: ``my_block.my_register``
38+
* :code-rst:`:rdl:ref:\`My Awesome Register <path.to.my_block.my_register>\`` displays custom text: ``My Awesome Register``
39+
40+
Whether the link points to PeakRDL-HTML reference, or an inline :rst:dir:`rdl:docnode`
41+
depends on the :confval:`peakrdl_default_link_to` setting.
42+
43+
44+
.. rst:role:: rdl:html-ref
45+
46+
Same as the :rst:role:`rdl:ref` role, except this will prefer linking to
47+
PeakRDL-HTML reference, regardless of the :confval:`peakrdl_default_link_to` setting.
48+
49+
.. rst:role:: rdl:doc-ref
50+
51+
Same as the :rst:role:`rdl:ref` role, except this will prefer linking to
52+
an inline :rst:dir:`docnode`, regardless of the :confval:`peakrdl_default_link_to` setting.

‎docs/examples/docnode.rst‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
Using the docnode directive
2+
===========================
3+
4+
.. tip::
5+
6+
To view the source of this document, click the "Show Source" option under
7+
the GitHub menu button on this page's header.
8+
9+
The :rst:dir:`rdl:docnode` directive can be used to insert the content of a
10+
single register model node into a document.
11+
12+
For example, one could insert the reference for the top-level SoC address layout using ...
13+
14+
.. code-block:: rst
15+
16+
.. rdl:docnode:: my_soc
17+
:link-to: doc
18+
19+
... which produces the following output:
20+
21+
--------------------------------------------------------------------------------
22+
23+
.. rdl:docnode:: my_soc

0 commit comments

Comments
 (0)