Merge branch 'doc_sphinx' into 'main'

Improve API documentation

See merge request campus/lenapy!12

Author: sfourest

.readthedocs.yaml

@@ -30,9 +30,9 @@ sphinx:
 # Optional but recommended, declare the Python requirements required
 # to build your documentation
 # See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
-python:
-   install:
-     - requirements: doc/requirements.txt
-
 conda:
   environment: doc/environment.yml
+python:
+  install:
+    - method: pip
+      path: .

doc/CHANGELOG.md CHANGELOG.mddoc/CHANGELOG.md renamed to CHANGELOG.md

@@ -0,0 +1,8 @@
+{{ fullname }}
+{{ underline }}
+
+
+.. automodule:: {{ fullname }}
+   :members:
+   :undoc-members:
+   :show-inheritance:

doc/.templates/autosummary/module.rst

@@ -0,0 +1,50 @@
+lenapy API Reference
+====================
+
+Module contents
+~~~~~~~~~~~~~~~
+
+.. autosummary::
+    :toctree: _autosummary
+
+    lenapy.lenapy_geo
+    lenapy.lenapy_time
+    lenapy.lenapy_ocean
+    lenapy.lenapy_harmo
+    lenapy.constants
+
+Submodules
+~~~~~~~~~~
+
+Readers
+*******
+
+Reader modules : define specific engines for the xarray.open_dataset() method
+
+.. autosummary::
+    :toctree: _autosummary
+
+    lenapy.readers.geo_reader
+    lenapy.readers.gravi_reader
+    lenapy.readers.ocean
+
+Utils
+*****
+
+Utils modules
+
+.. autosummary::
+    :toctree: _autosummary
+
+    lenapy.utils.harmo
+    lenapy.utils.gravity
+
+Writers
+*******
+
+Writer modules : define writers
+
+.. autosummary::
+    :toctree: _autosummary
+
+    lenapy.writers.gravi_writer

doc/api.rst

@@ -1 +1,2 @@
-.. mdinclude:: CHANGELOG.md
+.. _changes:
+.. mdinclude:: ../CHANGELOG.md

doc/api/index.rst

@@ -4,11 +4,17 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
 import datetime
+import inspect
 import os
 import sys
 
+__location__ = os.path.join(
+    os.getcwd(), os.path.dirname(inspect.getfile(inspect.currentframe()))
+)
+
 sys.path.insert(0, os.path.abspath(".."))
 sys.path.insert(0, os.path.abspath("../lenapy"))
+sys.path.insert(0, os.path.join(__location__, "../lenapy"))
 
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
@@ -46,6 +52,7 @@
 autoclass_content = "both"
 # sort class members by their order in the source
 autodoc_member_order = "bysource"
+autodoc_typehints = "both"
 
 # show all members of a class in the Methods and Attributes sections automatically
 numpydoc_show_class_members = True
@@ -66,17 +73,16 @@
 html_theme = "sphinx_rtd_theme"
 html_theme_options = {
     "logo_only": False,
-    "display_version": True,
     "prev_next_buttons_location": "both",
     "collapse_navigation": False,
     "sticky_navigation": True,
-    "navigation_depth": 4,
+    "navigation_depth": 3,
     "includehidden": True,
     "titles_only": False,
     "style_nav_header_background": "#2980B9",  # header color en haut à gauche
     # github_url for open access version
 }
-html_static_path = ["_static"]
+# html_static_path = ["_static"]
 
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {
@@ -94,3 +100,4 @@
 # See also:
 # https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html#confval-intersphinx_disabled_reftypes
 intersphinx_disabled_reftypes = ["*"]
+templates_path = [".templates"]

doc/changelog.rst

@@ -0,0 +1,112 @@
+Contributing
+============
+
+Thanks for helping to build lenapy!
+
+Retrieve the code: forking and cloning the Repository
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Make a fork of the `lenapy repo <https://github.com/CNES/lenapy>`__ and clone
+the fork.
+
+A documentation is available on GitHub to help platform users create a fork: `https://docs.github.com/fork-a-repo <https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo>`__
+
+.. code-block:: none
+
+   git clone https://github.com/<your-github-username>/lenapy.git
+   cd lenapy
+
+You may want to add ``https://github.com/CNES/lenapy`` as an upstream remote
+repository.
+
+.. code-block:: none
+
+   git remote add upstream https://github.com/CNES/lenapy
+
+Creating a Python environment
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+We have conda environment YAML file with all the necessary dependencies.
+
+.. code-block:: none
+
+   conda env create -f environment.yml --name=lenapy-dev
+
+to create a conda environment and install all the dependencies.
+
+Building lenapy
+~~~~~~~~~~~~~~~
+
+Lenapy is a pure-python repository. Development installation should be as simple as
+cloning the repository and running the following in the cloned directory:
+
+.. code-block:: none
+
+  conda activate lenapy-dev
+  python -m pip install --no-deps -e .
+
+If you have any trouble, please open an issue on the
+`lenapy issue tracker <https://github.com/CNES/lenapy/issues>`_.
+
+Style
+~~~~~
+
+Lenapy uses `black <http://black.readthedocs.io/en/stable/>`_ and `isort <https://isort.readthedocs.io/en/latest/>`_
+for formatting. If you installed lenapy with ``python -m pip install -e ".[dev]"`` these tools will already be
+installed.
+
+Running tests
+~~~~~~~~~~~~~
+
+Lenapy uses `pytest <https://docs.pytest.org/en/latest/>`_ for testing. You
+can run tests from the main lenapy directory as follows:
+
+.. code-block:: none
+
+    pytest tests
+
+Alternatively you may choose to run only a subset of the full test suite. For
+example to test only the `writers` submodule we would run tests as follows:
+
+.. code-block:: none
+
+    pytest tests/writers
+
+Coverage
+~~~~~~~~
+
+It is possible to check code coverage
+
+.. code-block:: none
+
+   pytest --cov=lenapy --cov-report=html
+
+You can still use all the usual pytest command-line options in addition to those.
+
+Pre-Commit Hooks
+~~~~~~~~~~~~~~~~
+
+Install and build the `pre commit <https://github.com/pre-commit/pre-commit>`_ tool as:
+
+.. code-block:: none
+
+    python -m pip install -e ".[dev]"
+    pre-commit install
+
+to install a few plugins like black, isort, and pylint. These tools will automatically
+be run on each commit. You can skip the checks with ``git commit --no-verify``.
+
+Documentation
+~~~~~~~~~~~~~
+
+We use `numpydoc <http://numpydoc.readthedocs.io/en/latest/format.html>`_ for our docstrings.
+
+Building the docs is possible with
+
+.. code-block:: none
+
+   $ conda env create -f environment.yml --name=lenapy-dev
+   $ conda activate lenapy-dev
+   $ python -m pip install -e ".[dev]"
+   $ cd doc
+   $ sphinx-build -b html doc doc/build

doc/conf.py

@@ -6,16 +6,19 @@ channels:
 dependencies:
   - python=3.11
   - esmpy>=8.4.0
+  - gsw>=3.6.16
   - pip>=20.1  # pip is needed as dependency
-  - pip:
-      - sphinx_rtd_theme
-      - sphinx-mdinclude
-      - nbsphinx          
-      - matplotlib>=3.6
-      - xarray>=2024.2
-      - gsw>=3.6.16
-      - netCDF4>=1.6.5
-      - pyyaml>=6.0
-      - dask>=2023.6
-      - xesmf>=0.8.2
+  - sphinx_rtd_theme
+  - sphinx-mdinclude
+  - nbsphinx
+  - matplotlib>=3.6
+  - xarray>=2024.2
+  - netCDF4>=1.6.5
+  - pyyaml>=6.0
+  - dask>=2023.6
+  - xesmf>=0.8.2
+  - cf_xarray
+  - pandas
+  - scipy
+
 

doc/contributing.rst

@@ -18,19 +18,13 @@ This library is based on the principle of class extension, i.e. functions can be
 Reading interfaces are implemented, enabling netcdf files to be opened with a compatible formalism from the **lenapy** library.
 
 .. toctree::
-   :maxdepth: 4
+   :maxdepth: 1
    :caption: Contents:
-   
-   changelog
+   :hidden:
+
    gettingStarted
-   api
+   Changelog <changelog>
    tutorials
-
-
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+   lenapy API Reference <api/index>
+   How to contribute <contributing>
+   Release procedure <release_procedure>