chore: add QuickOverview section (#171)

Co-authored-by: renaudjester <[email protected]> Adding an overview notebook for users to have something to start on to code with the toolbox.
mercator-ocean · Oct 28, 2024 · a77cece · a77cece
1 parent 7184848
commit a77cece
Show file tree

Hide file tree

Showing 17 changed files with 1,899 additions and 18 deletions.
diff --git a/.gitignore b/.gitignore
@@ -11,3 +11,6 @@ dist/
 
 # Sphinx documentation html build
 doc/_build/
+
+# Jupyter notebook checkpoints
+**/.ipynb_checkpoints/
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -28,6 +28,7 @@ repos:
         args: [--pytest-test-first]
         exclude: ^tests/resources/
       - id: pretty-format-json
+        exclude: ^doc/usage/quickoverview.ipynb
   - repo: https://github.com/pre-commit/mirrors-isort
     rev: v5.10.1
     hooks:

diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -33,3 +33,6 @@ python:
   install:
     - method: pip
       path: .
+
+#TODO: add environment variables if we want to build the notebook when building the documentation
+# https://docs.readthedocs.io/en/stable/environment-variables.html
diff --git a/CONTRIBUTION.md b/CONTRIBUTION.md
@@ -121,7 +121,7 @@ We use sphinx and read the docs to respectively build and distribute the documen
 
 We use:
 
-- autodoc: to create the documentation from the docstrings of the python interface or the comments in the models
+- autodoc: to create the documentation from the docstrings of the Python interface or the comments in the models
 - numpydoc: to convert numpydoc documentation to restructuresText
 - sphinx-click: to generate the documentation from the click CLI
 - furo: as a base template

diff --git a/conda_environment_sphinx.yaml b/conda_environment_sphinx.yaml
@@ -1,3 +1,4 @@
+name: conda-environment-sphinx
 dependencies:
   - python==3.9.18
   - pip
@@ -7,3 +8,7 @@ dependencies:
     - numpydoc==1.8.0
     - sphinx-copybutton==0.5.2
     - furo==2024.8.6
+    - myst_parser==3.0.1
+    - notebook==7.1.2
+    - ipywidgets==8.1.5
+    - matplotlib==3.9.2
diff --git a/doc/command-line-interface.rst b/doc/command-line-interface.rst
@@ -3,6 +3,7 @@
 Command line interface
 ===================================================
 
+.. _cli-intro:
 .. click:: copernicusmarine.command_line_interface.copernicus_marine:base_command_line_interface
     :prog: copernicusmarine
     :nested: short
@@ -14,19 +15,19 @@ Command line interface
     :nested: short
     :commands: describe
 
-
+.. _cli-subset:
 .. click:: copernicusmarine.command_line_interface.group_subset:subset
     :prog: subset
     :nested: short
     :commands: subset
 
-
+.. _cli-get:
 .. click:: copernicusmarine.command_line_interface.group_get:get
     :prog: get
     :nested: short
     :commands: get
 
-
+.. _cli-login:
 .. click:: copernicusmarine.command_line_interface.group_login:login
     :prog: login
     :nested: short

diff --git a/doc/conf.py b/doc/conf.py
@@ -8,7 +8,7 @@
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
-project = "Copernicus Marine Toolbox"
+project = "Copernicus Marine toolbox"
 copyright = "2024, Mercator Ocean International"
 author = "Mercator Ocean International"
 
@@ -20,6 +20,7 @@
     "sphinx_click",
     "numpydoc",
     "sphinx_copybutton",
+    "myst_nb",
 ]
 numpydoc_show_class_members = False
 
@@ -67,3 +68,8 @@
     "image/png",
     "image/jpeg",
 ]
+
+# -- Options for myst_nb --------------------------------------------------
+# https://myst-nb.readthedocs.io/en/latest/configuration.html#config-intro
+
+nb_execution_mode = "off"
diff --git a/doc/index.rst b/doc/index.rst
@@ -1,12 +1,12 @@
-.. Copernicus Marine Toolbox documentation master file, created by
+.. Copernicus Marine toolbox documentation master file, created by
    sphinx-quickstart on Wed Aug 21 14:04:51 2024.
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
 Copernicus Marine toolbox documentation
 =======================================
 
-The ``copernicusmarine`` Python library offers capabilities through both **Command Line Interface (CLI)** and **Python API**:
+The ``copernicusmarine`` Python library offers capabilities through both **command line interface (CLI)** and **Python API**:
 
 - **Metadata Information**: List and retrieve metadata information on all variables, datasets and products.
 - **Subset Datasets**: Subset datasets to extract only the parts of interest, in preferred format, such as Analysis-Ready Cloud-Optimized (ARCO) Zarr or NetCDF file format.

diff --git a/doc/installation.rst b/doc/installation.rst
@@ -1,8 +1,10 @@
+.. _installation-page:
+
 ===================================================
 Installing Copernicus Marine toolbox
 ===================================================
 
-There are several ways to install or use the Copernicus Marine Toolbox:
+There are several ways to install or use the Copernicus Marine toolbox:
 
 * via pip (see `PyPI repository <https://pypi.org/project/copernicusmarine/>`_)
 * via mamba | conda (see `conda-forge channel <https://anaconda.org/conda-forge/copernicusmarine>`_)

diff --git a/doc/usage/describe-usage.rst b/doc/usage/describe-usage.rst
@@ -1,3 +1,6 @@
+.. _describe-page:
+
+=====================
 Command ``describe``
 =====================
 

diff --git a/doc/usage/get-usage.rst b/doc/usage/get-usage.rst
@@ -1,3 +1,6 @@
+.. _get-page:
+
+===============
 Command ``get``
 ===============
 

diff --git a/doc/usage/login-usage.rst b/doc/usage/login-usage.rst
@@ -1,3 +1,6 @@
+.. _login-page:
+
+==================
 Command ``login``
 ==================
 

diff --git a/doc/usage/network-configuration.rst b/doc/usage/network-configuration.rst
@@ -15,7 +15,7 @@ to globally disable the usage of SSL in the toolbox:
 ``trust_env`` for Python libraries
 ------------------------------------
 
-To do HTTP calls, the Copernicus Marine Toolbox uses the ``requests`` library.
+To do HTTP calls, the Copernicus Marine toolbox uses the ``requests`` library.
 By default, this library will have ``trust_env`` values set to ``True``.
 
 If you want to deactivate this, you can set ``COPERNICUSMARINE_TRUST_ENV=False`` (default ``True``).

diff --git a/doc/usage/quickoverview.ipynb b/doc/usage/quickoverview.ipynb
diff --git a/doc/usage/quickstart.rst b/doc/usage/quickstart.rst
diff --git a/doc/usage/subset-usage.rst b/doc/usage/subset-usage.rst
@@ -1,3 +1,6 @@
+.. _subset-page:
+
+===================
 Command ``subset``
 ===================
 

diff --git a/doc/usage/usage.rst b/doc/usage/usage.rst
@@ -3,7 +3,7 @@ Usage and technical details
 
 .. toctree::
 
-    quickstart
+    quickoverview
     login-usage
     describe-usage
     subset-usage