Documentation

Docstrings

The API documentation is built from docstrings written with the code. We use numpy style docstrings. If you are adding a function or class, give it a numpy-style docstring and add the name of the function/class to the relevant .rst file in docs/api/, and it will be included in the documentation.

Documentation webpages

Sphinx

The present documentation is built with sphinx. If you installed huracanPy following the developers’ instruction, you should have the following package installed in your environment:

• sphinx

• pydata-sphinx-theme

• nbsphinx

• sphinx-copybutton

All documentations files are in the docs folder at the root of the package. They are either .rst (reStructured Text), .md (markdown), or .ipynb (Jupyter Notebook, which includes MarkDown) files.

Hint

To build the documentation locally, run make html in this folder. This is useful to preview your changes before you commit them.

To learn how to use these tools, you may want to check out the following resources:

• reStructuredText

  • Wikipedia page

  • Sphinx tutorial

  • Sphinx documentation

• Jupyter notebooks

  • Jupyter website

• Markdown

  • Jupyter doc

  • Markdown Guide

  • Markdown tutorial

  • MyST doc

• Sphinx

  • Documentation

  • Tutorial

You can also check out the source code of documentation pages you like to find how to do a specific thing.