Commit c7519592 authored by Jean-Baptiste Mouret's avatar Jean-Baptiste Mouret
Browse files

[ci-skip] split the tutorial for building the documentation and the tutorial for compilation

parent 6bb148f7
#!/bin/sh
echo "generating doxygen for Limbo, current path $PWD"
doxygen Doxyfile
#echo "generating default params"
#../waf default_params
Building the documentation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. note::
This section is only useful for developers who need to update the documentation.
We use:
- `Sphinx <http://sphinx-doc.org/>` for generating the documentation
- `Doxygen <http://www.stack.nl/~dimitri/doxygen/>` to extract information from the source code
- `Breathe <https://breathe.readthedocs.org/en/latest/>`_ to link Sphinx and doxygen
- `sphinx-versioning <https://robpol86.github.io/sphinxcontrib-versioning/>`_ (custom version) to generate a documentation for every version / branch
Install sphinx via pip: ::
sudo pip install Sphinx
sudo pip install sphinxcontrib-bibtex
sudo pip install breathe
sudo pip install git+https://github.com/resibots/sphinxcontrib-versioning.git@resibots
.. warning::
On Mac OSX, do not use `brew install sphinx` because this is not the right sphinx
.. note::
For Python 3, use `pip3` instead of `pip`
Install the Resibots theme for Sphinx::
git clone https://github.com/resibots/sphinx_resibots_theme
export SPHINX_RESIBOTS_THEME="/home/me/path/to/sphinx_resibots_theme"
Install `doxygen <http://www.stack.nl/~dimitri/doxygen/>`_ via your package manager (e.g. apt-get / brew)::
apt-get install doxygen
In the main limbo directory::
./waf docs
About sphinx and ReStructuredText:
- `There is a tutorial <http://sphinx-doc.org/tutorial.html>`_,
- `Primer for ReStructuredText <http://sphinx-doc.org/rest.html>`_, the markup language of Sphinx,
- `markup specific to Sphinx <http://sphinx-doc.org/markup/index.html>`_,
- `About C++ in Sphinx <http://sphinx-doc.org/domains.html#id2>`_
- `Breathe (bridge between sphinx and doxygen) <https://breathe.readthedocs.org/en/latest/>`_
- `Sphinx-versioning <https://robpol86.github.io/sphinxcontrib-versioning/>`_
......@@ -102,42 +102,3 @@ The second step is to run the build command::
Depending on your compiler, there may be some warnings, but the output should end with the following lines: ::
'build' finished successfully (time in sec)
Building the documentation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. note::
This section is only useful for developers who need to update the documentation.
Install sphinx via pip: ::
sudo pip install Sphinx
sudo pip install sphinxcontrib-bibtex
.. warning::
On Mac OSX, do not use `brew install sphinx` because this is not the right sphinx
Install the Resibots theme for Sphinx::
git clone https://github.com/resibots/sphinx_resibots_theme
export SPHINX_RESIBOTS_THEME="/home/me/path/to/sphinx_resibots_theme"
Install `breathe <https://breathe.readthedocs.io/en/latest/>`_ via pip::
sudo pip install breathe
Install `doxygen <http://www.stack.nl/~dimitri/doxygen/>`_ via your package manager (e.g. apt-get / brew)::
apt-get install doxygen
In the `doc` directory::
make html
About sphinx and ReStructuredText:
- `There is a tutorial <http://sphinx-doc.org/tutorial.html>`_,
- `Primer for ReStructuredText <http://sphinx-doc.org/rest.html>`_, the markup language of Sphinx,
- `markup specific to Sphinx <http://sphinx-doc.org/markup/index.html>`_,
- `About C++ in Sphinx <http://sphinx-doc.org/domains.html#id2>`_
- `Breathe (bridge between sphinx and doxygen) <https://breathe.readthedocs.org/en/latest/>`_
......@@ -12,3 +12,4 @@ Tutorials
external_libs
gp
opt
building_docs
......@@ -225,15 +225,16 @@ def shutdown(ctx):
def insert_license(ctx):
limbo.insert_license()
def build_docs(ctx):
print('extracting default params...')
def write_default_params(ctx):
print('extracting default params to docs/defaults.rst')
limbo.write_default_params('docs/defaults.rst')
print('Running doxygen')
s = "cd docs; doxygen Doxyfile; cd .."
retcode = subprocess.call(s, shell=True, env=None)
#print("to install sphinx-versioning: sudo pip3 install git+https://github.com/resibots/sphinxcontrib-versioning.git@resibots")
def build_docs(ctx):
print("generating HTML doc with versioning...")
print("to install sphinx-versioning: sudo pip3 install git+https://github.com/resibots/sphinxcontrib-versioning.git@resibots-theme")
s = 'sphinx-versioning -v build --whitelist-branches "(master|release-*)" docs docs/_build/html'
s = 'sphinx-versioning -v build -p docs/pre_script.sh --whitelist-branches "(master|doc_versioning|release-*)" docs docs/_build/html'
print(s)
retcode = subprocess.call(s, shell=True, env=None)
class BuildExtensiveTestsContext(BuildContext):
......@@ -251,3 +252,7 @@ class InsertLicense(BuildContext):
class BuildDoc(BuildContext):
cmd = 'docs'
fun = 'build_docs'
class BuildDoc(BuildContext):
cmd = 'default_params'
fun = 'write_default_params'
\ No newline at end of file
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