How to contribute to documentation?
Who should write documentation?
We gladly accept contributions of users, especially when it comes to providing simple examples of functions or write small parts of tutorials. Indeed, if you are learning to work with Green’s functions, it is very likely that you are writing some lines of codes to play with this container that could be very useful to future users.
If you are willing to contribute to this project, we however ask you to take the following steps:
- Check the Documentation and User guide sections of the website
- Check our Tutorials on github
- Respect our documentation conventions
As for code contribution, you are going to submit your changes as a pull request to the unstable branch of the triqs github. If you are unsure on how to do it, you can follow instructions here.
If you have any question, feel free to use our Google group.
Building the documentation
You first need to install sphinx:
pip install sphinx
When building the TRIQS project from sources, you should add the following flags to the cmake command:
Then move to the doc folder and build it:
cd doc && make
Because of the -DSphinx_Only=ON flag, this only generates html pages from rst files. If you also want to generate rst files from C++ examples, run:
and if you want the rst from headers, run:
Editing the documentation
You can now modify rst files in:
and see the output in:
In order not to rebuild the documentation by hand every time you make some changes, you can install sphinx-autobuild:
pip install sphinx-autobuild
sphinx-autobuild triqs.src/doc triqs.build/doc/html -c triqs.build/doc