From 647eb9746e2c2c11d04f6b631fff81818d0286e7 Mon Sep 17 00:00:00 2001 From: Nicolas Schmid Date: Wed, 22 May 2024 16:21:40 +0200 Subject: [PATCH 1/2] docs: add more examples on how to add write docs with sphinx --- docs/source/conf.py | 2 + docs/source/user/docs.md | 106 ++++++++++++++++++++++++++++++++++++++- 2 files changed, 106 insertions(+), 2 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index bf45287..5762fec 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -24,6 +24,8 @@ 'nbsphinx_link' ] +autosectionlabel_prefix_document = True + templates_path = ['_templates'] exclude_patterns = [] napoleon_custom_sections = [('Returns', 'params_style')] diff --git a/docs/source/user/docs.md b/docs/source/user/docs.md index eab6aa0..9d4cc3e 100644 --- a/docs/source/user/docs.md +++ b/docs/source/user/docs.md @@ -7,11 +7,113 @@ - `make server` to build the documentation and start a local server on http://localhost:8000 to view the documentation and rebuild automatically. - `make clean` to remove the built documentation. -## Writing the Documentation +## Structure of the Documentation Currently, the documentation has two main sections: The {doc}`index` which serves as a written tutorial for the project and the {doc}`../reference/index` which serves as a technical reference for the project. ### The User Guide This is a written tutorial for the project. It should be written in a way that a new user can understand and use the project. Background on methods and concepts can and should be included. ### The API Reference -This is a technical reference for the project. The user can go and look up the specifics of a method or class, including specific examples. This is generated to a big extent from the docstrings in the code. The developer mostly just needs to decide on the structure of this part of the documentation, and write the docstrings in the code accordingly. \ No newline at end of file +This is a technical reference for the project. The user can go and look up the specifics of a method or class, including specific examples. This is generated to a big extent from the docstrings in the code. The developer mostly just needs to decide on the structure of this part of the documentation, and write the docstrings in the code accordingly. + +## Technical Details +### How to Autogenerate Documentation +It is possible to autogenerate documentation from the docstrings in the code. We use this feature to generate the API reference. The docstrings should be written in reStructuredText format, using the [Google Style Python Docstrings](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html). + +#### How to Add a New Section +First, create a new `.md` file in the `/docs/source/reference` directory and add the new file to the `toctree` in `/docs/source/reference/index.md`. + +At the start of the file you can define the current module, which will be used to find the functions and classes in the module. This is done with the following code (the `>` characters are added to avoid execution of the directives): +```` +> ```{eval-rst} +> .. currentmodule:: seismostats +> ``` +```` +You can then add the references to the functions and classes using the relative import path to the function +or class name. +```` +> ```{eval-rst} +> .. autosummary:: +> :toctree: api/ +> +> Catalog +> ``` +```` +This creates a list of references to the functions and classes, as well as, inside the `api` directory, a `.rst` file with the documentation for the functions and classes. + +Optimally you would structure this documentation logically, and provide a minimal description of the groups +of functions and classes. + +If you would like to have the documentation for a function or class directly in the current file, you can first use the `currentmodule` as above, and then the `autofunction` directive. +```` +> ```{eval-rst} +> .. autofunction:: _example +> ``` +```` + + +### How to Use Crossreferences + +#### Document +How to reference a document in the documentation. + +**Code** +``` +Using a custom name: {doc}`Reference <../reference/index>` +Using the title of the document: {doc}`../reference/index` +``` + +**Output** +Using a custom name: {doc}`Reference <../reference/index>` +Using the top level title of the document: {doc}`../reference/index` + +#### Reference +How to reference a section in the documentation. + +**Code** +``` +Using a custom name: {ref}`Reference ` +Using the title of the section: {ref}`/reference/catalog.md#transformation` +``` + +**Output** +Using a custom name: {ref}`Reference ` +Using the title of the section: {ref}`/reference/catalog.md#transformation` + +#### Function / Class +How to reference a function or class in the documentation. + +**Code** +``` +Using a custom name: {func}`Bin Magnitudes ` +Using the function name: {func}`~seismostats.Catalog.bin_magnitudes` +Or with the whole path: {func}`seismostats.Catalog.bin_magnitudes` +``` + +**Output** +Using a custom name: {func}`Bin Magnitudes ` +Using the title of the function: {func}`~seismostats.Catalog.bin_magnitudes` +Or with the whole path: {func}`seismostats.Catalog.bin_magnitudes` + +#### Use Crossreferences in a Docstring +How to use crossreferences in a docstring. + +**Code** +```python +def _example(): + """ + This function is purely used as an example for the documentation. + + See Also: + :func:`seismostats.Catalog.bin_magnitudes` + """ + pass +``` + +**Output** +```{eval-rst} +.. module:: seismostats.utils.docs +``` +```{eval-rst} +.. autofunction:: _example +``` From 6a30ddf56b1875fb94e67c9a1c6e0f5ff95621ad Mon Sep 17 00:00:00 2001 From: Nicolas Schmid Date: Wed, 22 May 2024 16:23:05 +0200 Subject: [PATCH 2/2] docs: add example function needed for documentation --- seismostats/utils/docs.py | 8 ++++++++ 1 file changed, 8 insertions(+) create mode 100644 seismostats/utils/docs.py diff --git a/seismostats/utils/docs.py b/seismostats/utils/docs.py new file mode 100644 index 0000000..40fcdda --- /dev/null +++ b/seismostats/utils/docs.py @@ -0,0 +1,8 @@ +def _example(): + """ + This function is purely used as an example for the documentation. + + See Also: + :func:`seismostats.Catalog.bin_magnitudes` + """ + pass