Documentation Guidelines
To get to explain how code works, we need to get some documentation in our code, and in this document, you have some of the rules we created for OpenAlea.
Openalea uses Sphinx to generate our documentation and ReadTheDocs to build it and generate the OpenAlea website.
To stay in the same style as us, you need to work with the Read the Docs Sphinx Theme. The theme can be installed like this :
pip install sphinx_rtd_theme
Once you’ve installed the theme, write in your conf.py file :
html_theme = "sphinx_rtd_theme"
Then write in the same file :
html_theme_options = { 'logo_only': True }
Download the OpenAlea logo and put it your _static directory and then write in your conf.py file
You can find the official logos here.
Among those, we recommend using this logo :
You will also need to execute those two lines of code :
html_static_path = ['_static']
html_logo = "_static/openalea_web.svg"
Docstring are the fundamentals of explaining the code and what it does to people who want to either use or modify the code. OpenAlea uses autodoc from Sphinx to compile automatically the documentation from docstrings, and ReadTheDocs put them into the OpenAlea website.
-
Docstrings must be surrounded by triple quotes
-
Parameters must follow the following schema :
Parameters
----------
Var1 : type
Description of `Var1`
Var2
Description of `Var2` (type not specified)
- Returns are pretty similar :
Returns
-------
Var3 : int
Description `Var3`
- Errors can be detailed in a special field :
Raises
------
ErrorRaised
Brief explanation of the error.
We use the NumPy docstring style, with more information here.
Here is an example of a documented function
def function(x: int, y: float, z: str = None) -> int:
"""
Main purpose of the function.
Parameters
----------
x : integer
Any information about `x`
y : float
Additional info about `y`
z : String
Additional info about `z`
Additional information can fit here.
Returns
-------
int
details about the return value
Raises
------
ValueError
if `x == 0`
"""
pass
README files are generally using Markdown in our packages, and should contain the following information :
- Information about the package :
- Authors
- Institute
- Status : what is is, which language it uses (e.g. : Python package)
- License
- URL of the official website or official documentation
- Description : What does the package do.
- Installation : How to install the package from a shell.
- Configuration : What do you need to install this package.
- Usage : Short tutorial on how to use the module for a non-specialized audience
- Sponsors
- Contribution : link to Git workflow
WIP