Doc WIP

Signed-off-by: Alexis Jeandet <alexis.jeandet@member.fsf.org>
SciQLop · jeandet · Feb 3, 2022 · Nov 4, 2021 · Jan 19, 2022 · Jan 20, 2022
commit 541d871678c53ea75de470352f3979f988b87840
diff --git a/Makefile b/Makefile
@@ -69,9 +69,9 @@ coverage: ## check code coverage quickly with the default Python
 	$(BROWSER) htmlcov/index.html
 
 docs: ## generate Sphinx HTML documentation, including API docs
-	rm -f docs/speasy.rst
-	rm -f docs/modules.rst
-	sphinx-apidoc -M -o docs/ speasy
+	rm -f docs/dev/speasy.rst
+	rm -f docs/dev/modules.rst
+	sphinx-apidoc -M -o docs/dev speasy
 	$(MAKE) -C docs clean
 	$(MAKE) -C docs html
 	$(BROWSER) docs/_build/html/index.html

diff --git a/docs/dev_index.rst → docs/dev/index.rst b/docs/dev_index.rst → docs/dev/index.rst
diff --git a/docs/modules.rst → docs/dev/modules.rst b/docs/modules.rst → docs/dev/modules.rst
diff --git a/docs/dev/speasy.common.rst b/docs/dev/speasy.common.rst
@@ -0,0 +1,18 @@
+speasy.common package
+=====================
+
+.. automodule:: speasy.common
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Submodules
+----------
+
+speasy.common.variable module
+-----------------------------
+
+.. automodule:: speasy.common.variable
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/dev/speasy.config.rst b/docs/dev/speasy.config.rst
@@ -0,0 +1,7 @@
+speasy.config package
+=====================
+
+.. automodule:: speasy.config
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/dev/speasy.core.cache.rst b/docs/dev/speasy.core.cache.rst
@@ -0,0 +1,26 @@
+speasy.core.cache package
+=========================
+
+.. automodule:: speasy.core.cache
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Submodules
+----------
+
+speasy.core.cache.cache module
+------------------------------
+
+.. automodule:: speasy.core.cache.cache
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+speasy.core.cache.version module
+--------------------------------
+
+.. automodule:: speasy.core.cache.version
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/dev/speasy.core.proxy.rst b/docs/dev/speasy.core.proxy.rst
@@ -0,0 +1,7 @@
+speasy.core.proxy package
+=========================
+
+.. automodule:: speasy.core.proxy
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/dev/speasy.core.rst b/docs/dev/speasy.core.rst
@@ -0,0 +1,43 @@
+speasy.core package
+===================
+
+.. automodule:: speasy.core
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Subpackages
+-----------
+
+.. toctree::
+   :maxdepth: 4
+
+   speasy.core.cache
+   speasy.core.proxy
+
+Submodules
+----------
+
+speasy.core.datetime\_range module
+----------------------------------
+
+.. automodule:: speasy.core.datetime_range
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+speasy.core.http module
+-----------------------
+
+.. automodule:: speasy.core.http
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+speasy.core.span\_utils module
+------------------------------
+
+.. automodule:: speasy.core.span_utils
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/dev/speasy.inventory.rst b/docs/dev/speasy.inventory.rst
@@ -0,0 +1,26 @@
+speasy.inventory package
+========================
+
+.. automodule:: speasy.inventory
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Submodules
+----------
+
+speasy.inventory.data\_tree module
+----------------------------------
+
+.. automodule:: speasy.inventory.data_tree
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+speasy.inventory.indexes module
+-------------------------------
+
+.. automodule:: speasy.inventory.indexes
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/dev/speasy.products.rst b/docs/dev/speasy.products.rst
@@ -0,0 +1,42 @@
+speasy.products package
+=======================
+
+.. automodule:: speasy.products
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Submodules
+----------
+
+speasy.products.catalog module
+------------------------------
+
+.. automodule:: speasy.products.catalog
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+speasy.products.dataset module
+------------------------------
+
+.. automodule:: speasy.products.dataset
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+speasy.products.timetable module
+--------------------------------
+
+.. automodule:: speasy.products.timetable
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+speasy.products.variable module
+-------------------------------
+
+.. automodule:: speasy.products.variable
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/dev/speasy.rst b/docs/dev/speasy.rst
@@ -0,0 +1,20 @@
+speasy package
+==============
+
+.. automodule:: speasy
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Subpackages
+-----------
+
+.. toctree::
+   :maxdepth: 4
+
+   speasy.common
+   speasy.config
+   speasy.core
+   speasy.inventory
+   speasy.products
+   speasy.webservices
diff --git a/docs/dev/speasy.webservices.amda.rst b/docs/dev/speasy.webservices.amda.rst
@@ -0,0 +1,58 @@
+speasy.webservices.amda package
+===============================
+
+.. automodule:: speasy.webservices.amda
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Submodules
+----------
+
+speasy.webservices.amda.exceptions module
+-----------------------------------------
+
+.. automodule:: speasy.webservices.amda.exceptions
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+speasy.webservices.amda.indexes module
+--------------------------------------
+
+.. automodule:: speasy.webservices.amda.indexes
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+speasy.webservices.amda.inventory module
+----------------------------------------
+
+.. automodule:: speasy.webservices.amda.inventory
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+speasy.webservices.amda.rest\_client module
+-------------------------------------------
+
+.. automodule:: speasy.webservices.amda.rest_client
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+speasy.webservices.amda.utils module
+------------------------------------
+
+.. automodule:: speasy.webservices.amda.utils
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+speasy.webservices.amda.ws module
+---------------------------------
+
+.. automodule:: speasy.webservices.amda.ws
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/dev/speasy.webservices.cda.rst b/docs/dev/speasy.webservices.cda.rst
@@ -0,0 +1,7 @@
+speasy.webservices.cda package
+==============================
+
+.. automodule:: speasy.webservices.cda
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/dev/speasy.webservices.csa.rst b/docs/dev/speasy.webservices.csa.rst
@@ -0,0 +1,7 @@
+speasy.webservices.csa package
+==============================
+
+.. automodule:: speasy.webservices.csa
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/dev/speasy.webservices.rst b/docs/dev/speasy.webservices.rst
@@ -0,0 +1,18 @@
+speasy.webservices package
+==========================
+
+.. automodule:: speasy.webservices
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Subpackages
+-----------
+
+.. toctree::
+   :maxdepth: 4
+
+   speasy.webservices.amda
+   speasy.webservices.cda
+   speasy.webservices.csa
+   speasy.webservices.ssc
diff --git a/docs/dev/speasy.webservices.ssc.rst b/docs/dev/speasy.webservices.ssc.rst
@@ -0,0 +1,18 @@
+speasy.webservices.ssc package
+==============================
+
+.. automodule:: speasy.webservices.ssc
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Submodules
+----------
+
+speasy.webservices.ssc.indexes module
+-------------------------------------
+
+.. automodule:: speasy.webservices.ssc.indexes
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/index.rst b/docs/index.rst
@@ -6,7 +6,7 @@ Welcome to Speasy's user documentation!
 
    readme
    installation
-   user_modules
-   dev_index
+   user/modules
+   dev/index
 
-:doc:`Go to developers doc <dev_index>`
+:doc:`Go to developers doc <dev/index>`
diff --git a/docs/amda.rst → docs/user/amda/amda.rst b/docs/amda.rst → docs/user/amda/amda.rst
@@ -8,6 +8,45 @@ AMDA
    amda_examples
    amda_notebooks
 
+AMDA is one of the main data providers that speasy handles. Most products are either available using directly the AMDA module or using :meth:`speasy.get_data()`.
+The following documentation will focus on AMDA module specific usage.
+
+All examples assumes that you imported AMDA module like this:
+
+    >>> from speasy import amda
+
+Getting data from AMDA
+----------------------
+
+`AMDA <http://amda.irap.omp.eu/>`_ distributes several products such as Parameters, user Parameters, Datasets, Timetables, user Timetables, Catalogs
+and user Catalogs. Speasy makes them accessible thanks to this module with :meth:`~speasy.webservices.amda.ws.AMDA_Webservice.get_data()`
+or their dedicated methods such as :meth:`~speasy.webservices.amda.ws.AMDA_Webservice.get_parameter()`, :meth:`~speasy.webservices.amda.ws.AMDA_Webservice.get_user_parameter()`,...
+Note that you can browse the list of all available products from `AMDA <http://amda.irap.omp.eu/>`_ Workspace:
+
+.. image:: images/AMDA_workspace_collapsed.png
+   :width: 30%
+   :alt: AMDA workspace collapsed
+.. image:: images/AMDA_workspace_params.png
+   :width: 30%
+   :alt: AMDA workspace collapsed
+.. image:: images/AMDA_workspace_timetables.png
+   :width: 30%
+   :alt: AMDA workspace collapsed
+
+This module provides two kinds of operations, `list` or `get` and so user methods are prefixed with one of them.
+- `get` methods retrieve the given product from AMDA server, they takes at least the product identifier and time range for time series
+- `list` methods list available products of a given type on AMDA, they return a list of indexes that can be passed to a `get` method
+
+Let's start with a simple example, we want to download the first parameter available on AMDA:
+
+    >>> first_param_index=amda.list_parameters()[0]
+    >>> first_param=amda.get_parameter(first_param_index, "2018-01-01", "2018-01-02")
+    >>> first_param.columns
+    ['imf_mag']
+    >>> len(first_param.time)
+    5400
+
+
 
 Getting AMDA_Webservice dataset and parameters
 ----------------------------------------------

diff --git a/docs/amda_catalogs.rst → docs/user/amda/amda_catalogs.rst b/docs/amda_catalogs.rst → docs/user/amda/amda_catalogs.rst
diff --git a/docs/amda_datasets.rst → docs/user/amda/amda_datasets.rst b/docs/amda_datasets.rst → docs/user/amda/amda_datasets.rst
diff --git a/docs/amda_example_1.rst → docs/user/amda/amda_example_1.rst b/docs/amda_example_1.rst → docs/user/amda/amda_example_1.rst
@@ -3,4 +3,4 @@ AMDA_Webservice Example 1: getting public dataset and parameter
 
 In this script we download the :data:`tao-ura-sw` dataset and the :data:`imf` parameter on AMDA_Webservice.
 
-.. literalinclude:: ../examples/amda_public_data.py
+.. literalinclude:: ../../examples/amda_public_data.py
diff --git a/docs/amda_example_2.rst → docs/user/amda/amda_example_2.rst b/docs/amda_example_2.rst → docs/user/amda/amda_example_2.rst
@@ -3,4 +3,4 @@ AMDA_Webservice Example 2: getting user defined parameter
 
 The following example illustrates how to access parameters defined on your user account within AMDA_Webservice.
 
-.. literalinclude:: ../examples/amda_user_parameter.py
+.. literalinclude:: ../../examples/amda_user_parameter.py