mrcmry / spinaldoc-rtd

The sources of the online SpinalHDL doc

SpinalDoc

This is the documentation repository for SpinalHDL.

It is published on spinalhdl.github.io/SpinalDoc-RTD.

There is also a Chinese version on spinalhdl-cn.github.io/SpinalDoc-RTD. This continuous localization version is maintained with the help of Weblate.

You can also find the API documentation on spinalhdl.github.io/SpinalHDL.

How to build this documentation

With venv

Requirements (system)

• make
• git

Create a virtual environment with pipenv (will use the Pipfile for installing the necessary packages)

python3 -m venv .venv

then you can activate the virtual environment (in bash) and install the dependencies

source .venv/bin/activate
pip install -r requirements.txt

and then you can use make the usual way

make html     # for html
make latex    # for latex
make latexpdf # for latex (will require latexpdf installed)
make          # list all the available output format

all the outputs will be in docs folder (for html: docs/html)

The Chinese version can be built by

make -e SPHINXOPTS="-D language='zh_CN'" html # for html in Chinese

With Docker

Requirements (system):

• docker
• git

To create the custom docker image (with python and its dependencies):

docker build -t spinaldoc-rtd .

Then to build the docs:

docker run -it --rm -v $PWD:/docs spinaldoc-rtd

You can still run custom commands in the docker, for instance to clean:

docker run -it --rm -v $PWD:/docs spinaldoc-rtd make clean

It is also possible to create the custom docker image to build a pdf (heavier):

docker build -f pdf.Dockerfile -t spinaldoc-pdf .

And to run it:

docker run -it --rm -v $PWD:/docs spinaldoc-pdf

Native

Requirements (system):

• make
• git

Requirements (Python 3):

• sphinx
• sphinx-rtd-theme
• sphinxcontrib-wavedrom
• sphinx-multiversion

After installing the requirements you can run

make html     # for html
make latex    # for latex
make latexpdf # for latex (will require latexpdf installed)
make          # list all the available output format

you can create build multiple version of the doc via

sphinx-multiversion source docs/html

in the docs/html there will be a folder with the builded doc for each branch and tag