Contribute to docs¶
How to build the docs locally¶
To build the docs, clone the repository:
$ git clone https://github.com/pypr/pysph
Make sure to work in an pysph
environment. I will proceed with the further
instructions assuming that the repository is cloned in home directory. Change to
the docs
directory and run make html
.
$ cd ~/pysph/docs/
$ make html
Possible error one might get is:
$ sphinx-build: Command not found
Which means you don’t a have sphinx-build in your system. To install across the system do:
$ sudo apt-get install python3-sphinx
or to install in an environment locally do:
$ pip install sphinx
run make html
again. The documentation is built locally at
~/pysph/docs/build/html
directory. Open `index.html
file by running
$ cd ~/pysph/docs/build/html
$ xdg-open index.html
How to add the documentation¶
As a starting point one can add documentation to one of the examples in
~/pysph/pysph/examples
folder. There is a dedicated
~/pysph/docs/source/examples
directory to add documentation to examples.
Choose an example to write documentation for,
$ cd ~/pysph/docs/source/examples
$ touch your_example.rst
We will write all the documentation in rst
file format. The index.rst
file in the examples directory should know about our newly created file, add a
reference next to the last written example.:
* :ref:`Some_example`:
* :ref:`Other_example`:
* :ref:`taylor_green`: the Taylor-Green Vortex problem in 2D.
* :ref:`sphere_in_vessel`: A sphere floating in a hydrostatic tank example.
* :ref:`your_example_file`: Description of the example.
and at the top of the example file add the reference, for example in
your_example_file.rst
, you should add,:
.. _your_example_file
That’s it, add the documentation and send a pull request.