Commit 4fdc6b41 authored by VIGNET Pierre's avatar VIGNET Pierre
Browse files

[doc] Add doc to build doc; fix link issues

parent 199e2d49
......@@ -70,12 +70,67 @@ Build environment setup
Once you’ve cloned your fork of the Cadbiom repository, you should set up a Python development environment tailored for Cadbiom.
See the chapter `Setting up a virtual environment <./installation.html#setting-up-a-virtual-environment>`_ of the installation process.
See the chapter :ref:`setting_up_a_virtual_environment` of the installation process.
Then see the chapter `Install the development version <./installation.html#install-the-development-version>`_.
Then see the chapter :ref:`install_dev_version`.
Bugs
----
Documentation
-------------
Documentation is built using `Sphinx <http://sphinx-doc.org/>`_ and hosted `cadbiom.genouest.org <http://cadbiom.genouest.org/doc/cadbiom>`_.
Documentation is mostly written as `reStructuredText <http://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`_
(.rst) files, but they can also be Markdown (.md) files. There are advantages to both formats:
- reStructuredText enables python-generated text to fill your documentation as in the auto-importing
of modules or usage of plugins like `sphinx-argparse`.
- Markdown is more intuitive to write and is widely used outside of python development.
If you don't need autogeneration of help documentaiton, then you may want to stick with writing Markdown.
Here's a subset of reStructuredText to help you get started writing these files:
- `Full specification <https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html>`_
- `Quick references for Sphinx <https://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html>`_
Human-readable command-line documentation is written using a Sphinx extension called
`sphinx-argparse <https://sphinx-argparse.readthedocs.io/en/latest/index.html>`_.
Folder structure
~~~~~~~~~~~~~~~~
The documentation source-files are located in ``./doc/source/``, with ``./doc/source/index.rst`` being the main entry point.
Each subsection of the documentation is a ``.rst`` file inside ``./doc/source/``.
Html files are generated in ``./doc/build/``.
Building documentation
~~~~~~~~~~~~~~~~~~~~~~
Building the documentation locally is useful to test changes.
First, make sure you have the development dependencies installed; See `Build environment setup`_
Then build the HTML output format by running:
.. code-block:: bash
make doc
# or
make -C ./doc html
Sphinx caches built documentation by default, which is generally great, but can cause the sidebar
of pages to be stale. You can clean out the cache with:
.. code-block:: bash
make -C ./doc clean
Report bugs
-----------
Please `report bugs on GitLab <https://gitlab.inria.fr/pvignet/cadbiom/issues>`_.
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment