Changeset View
Changeset View
Standalone View
Standalone View
README.md
Show All 9 Lines | |||||
documentation coming from other modules of the stack. | documentation coming from other modules of the stack. | ||||
All documentation is written and typeset using [Sphinx][1]. General | All documentation is written and typeset using [Sphinx][1]. General | ||||
documentation is shipped as part of this module. Module-specific documentation | documentation is shipped as part of this module. Module-specific documentation | ||||
is centralized here via symlinks to the `docs/` dirs of individual modules. | is centralized here via symlinks to the `docs/` dirs of individual modules. | ||||
Therefore to build the full documentation you need a working and | Therefore to build the full documentation you need a working and | ||||
complete [Software Heritage development environment][2]. | complete [Software Heritage development environment][2]. | ||||
[1]: http://www.sphinx-doc.org/ | |||||
[2]: https://forge.softwareheritage.org/source/swh-environment/ | |||||
How to build the doc | How to build the doc | ||||
-------------------- | -------------------- | ||||
Install the [Software Heritage development environment][2] | |||||
$ git clone https://forge.softwareheritage.org/source/swh-environment | |||||
$ cd swh-environment | |||||
$ ./bin/update # this will clone needed git repos, inc. swh-doc | |||||
$ cd swh-doc | |||||
Ensure you have the required tools to generate images ([graphviz][3]'s `dot` | Ensure you have the required tools to generate images ([graphviz][3]'s `dot` | ||||
and [plantuml][4]). On a Debian system: | and [plantuml][4]). On a Debian system: | ||||
$ sudo apt install plantuml graphviz | $ sudo apt install plantuml graphviz | ||||
[3]: https://graphviz.org | |||||
[4]: http://plantuml.com | |||||
It is also recomanded to build the doc using [tox][5], so ensure you have it | |||||
installed, eg. on a Debian system: | |||||
Then | $ sudo apt install tox | ||||
$ cd docs | |||||
$ make html | |||||
Behind the scene, this will do two things: | Then (from the `swh-environment/swh-doc/` directory): | ||||
$ tox -e sphinx-dev | |||||
This tox environment will build the documentation from the sources available in | |||||
the parent directory (`swh-environment`). | |||||
### 1. Generate sphinx-apidoc rst documents for all modules | Behind the scene, this tox environment will run the sphinx documentation | ||||
building process via [pifpaf][6] to encapsulate the need os Postgresql to | |||||
generate database schemas. The documentation building process itself consists | |||||
mainly in 3 steps: | |||||
### 1. Generate documentation assets for all modules | |||||
$ cd swh-environment | $ cd swh-environment | ||||
$ make docs-apidoc | $ make docs-assets | ||||
This will *not* build the documentation in each module (there is `make docs` | This will *not* build the documentation in each module (there is `make docs` | ||||
for that), but will use `sphinx-apidoc` to generate documentation indexes for | for that). | ||||
each (sub)modules in the various Software Heritage components. | |||||
As `sphinx-apidoc` refuses to overwrite old documents, before proceeding you | |||||
might need to clean up old cruft with: | |||||
$ cd swh-environment | ### 2. Build the api docs for all swh python packages | ||||
$ make docs-clean | |||||
$ cd swh-docs/docs | |||||
$ make apidoc | |||||
### 2. Build the documentation | ### 3. Build the documentation | ||||
$ cd swh-docs/docs | $ cd swh-docs/docs | ||||
$ make | $ make | ||||
The HTML documentation is now available starting from `_build/html/index.html`. | The HTML documentation is now available starting from `_build/html/index.html`. | ||||
Cleaning up | Cleaning up | ||||
----------- | ----------- | ||||
$ cd docs | $ cd docs | ||||
$ make distclean | $ make distclean | ||||
The former (`make clean`) will only clean the local Sphinx build, without | The former (`make clean`) will only clean the local Sphinx build, without | ||||
touching other modules. The latter (`make distclean`) will also clean Sphinx | touching other modules. The latter (`make distclean`) will also clean Sphinx | ||||
builds in all other modules. | builds in all other modules. | ||||
Publishing the doc | Publishing the doc | ||||
------------------ | ------------------ | ||||
$ cd docs | The publication of the documentation is now managed by the [CI][7]. | ||||
$ make install | |||||
$ xdg-open https://docs.softwareheritage.org/devel/ | |||||
For the above to work you need to have ssh access into the machine | |||||
hosting <https://docs.softwareheritage.org> (currently `pergamon`), and write | [1]: http://www.sphinx-doc.org/ | ||||
access do the document root directory of that virtual host (currently granted | [2]: https://forge.softwareheritage.org/source/swh-environment/ | ||||
to all members of the `swhdev` UNIX group on Software Heritage machines). | [3]: https://graphviz.org | ||||
[4]: http://plantuml.com | |||||
[5]: https://tox.readthedocs.io/ | |||||
[6]: https://github.com/jd/pifpaf |