Documentation
Content
Documentation#
High-quality and consistent documentation is very important for any coding project, but even more when distributing your project. A well written documentation allows new users to find out how to use Sarkas as well as helps developers (like you!) to understand the best practices.
Sarkas uses the popular Python documentation generator Sphinx. Sphinx translates a set of plain text source files (often written in reStructuredText) to HTML files, automatically producing cross-references, indices, etc. If you haven’t worked with Sphinx before, you should first read their quickstart guide.
Install Required Packages#
Sarkas documentation build requires additional packages. Open a Teminal window and activate your sarkas environment
$ conda activate sarkas
Move into the sarkas-master/docs/
directory, using cd
commands, and type the following
$ conda install --file requirements.txt -c conda-forge
The above command will install the packages listed in requirements.txt
using the conda channel conda-forge
.
If your changes require the installation of a new package please add to the requirements.txt
file.
Writing Documentation#
When making or adding changes to Sarkas source code an example .ipynb
notebook and/or an .rst
file
should be created to demonstrate how it works.
A good example are the notebooks in the tutorial page.
You will also need to add the .rst
file and/or .ipynb
notebook’s path in the relevant section in the
index.rst
file (you can find this in sarkas-master/docs/
).
Besides this, the functions and classes in your code must always contain docstrings.
Sphinx uses these docstrings to auto-generate the API documentation for the entire Sarkas package.
Note
Please make sure that you have correctly formatted the docstrings by checking how the corresponding module’s API looks once you build the documentation.
Building Documentation#
Once you have updated the documentation we can check our changes by building it locally on your machine. Here are the steps:
Make sure to activate your sarkas
environment: open a terminal window and type
$ conda activate sarkas
This is needed because when building the documentation you import the sarkas
package, see the line import sarkas
in the file conf.py
.
Then run the following
$ make clean && make html
The first command removes all the content in _build/html
. This command is not necessary, but suggested
so to avoid any conflicts.
The second command updates the documentation with your changes and creates html files in the folder _build/html
.
Fix any Error and/or Warning messages. You might need to run the command few times.
You can ignore warnings about duplicate citations.
Check the changes in the Documentation by opening any of the new/updated .html
files using a browser. Note you need to look at the files in _build/html
as these are the new/updated ones.
Congratulations! The Documentation is up to date.