https://github.com/SpinalHDL/SpinalDoc-RTD

The sources of the online SpinalHDL doc
https://github.com/SpinalHDL/SpinalDoc-RTD

documentation spinalhdl

Last synced: 2 months ago
JSON representation

The sources of the online SpinalHDL doc

• Host: GitHub
• URL: https://github.com/SpinalHDL/SpinalDoc-RTD
• Owner: SpinalHDL
• License: cc0-1.0
• Created: 2018-10-29T18:49:30.000Z (about 6 years ago)
• Default Branch: master
• Last Pushed: 2024-08-20T05:02:24.000Z (5 months ago)
• Last Synced: 2024-08-20T10:57:52.621Z (5 months ago)
• Topics: documentation, spinalhdl
• Language: Python
• Homepage: https://spinalhdl.github.io/SpinalDoc-RTD/
• Size: 920 MB
• Stars: 24
• Watchers: 11
• Forks: 61
• Open Issues: 26
• Metadata Files:
  • Readme: README.rst
  • License: LICENSE

Awesome Lists containing this project

README

        
=========

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)

.. code:: shell

   python3 -m venv .venv

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

.. code:: shell

   source .venv/bin/activate

   pip install -r requirements.txt

and then you can use ``make`` the usual way

.. code:: shell

   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

.. code:: shell

   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):

.. code:: shell

   docker build -t spinaldoc-rtd .

Then to build the docs:

.. code:: shell

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

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

.. code:: shell

   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):

.. code:: shell

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

And to run it:

.. code:: shell

   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

.. code:: shell

   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

.. code:: shell

   sphinx-multiversion source docs/html

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