[Doc] some cleanups, still a lot to do

Signed-off-by: Alexis Jeandet <alexis.jeandet@member.fsf.org>
SciQLop · Oct 7, 2021 · 8ba0eea · 8ba0eea
1 parent 637ce68
commit 8ba0eea
Show file tree

Hide file tree

Showing 28 changed files with 168 additions and 80 deletions.
diff --git a/AUTHORS.rst b/AUTHORS.rst
@@ -10,8 +10,8 @@ Development Lead
 Contributors
 ------------
 
-AMDA_Webservice
-^^^^
+AMDA Webservice
+^^^^^^^^^^^^^^^
 
 * Alexandre Schulz <alexandre.schulz@irap.omp.eu>
 * Benjamin Renard <benjamin.renard@irap.omp.eu>
diff --git a/docs/amda.rst b/docs/amda.rst
@@ -16,7 +16,7 @@ First import AMDA connection object::
 
     >>> from speasy import amda
 
-Downloading the data is done by using the :meth:`speasy.webservices.amda.ws.AMDA_Webservice.get_data()` or :meth:`speasy.amda.amda.AMDA_Webservice.get_parameter()` methods. For example
+Downloading the data is done by using the :meth:`speasy.webservices.amda.ws.AMDA_Webservice.get_data()` or :meth:`speasy.webservices.amda.ws.AMDA_Webservice.get_parameter()` methods. For example
 getting `imf` data between 2000-01-01 and 2000-02-01::
 
     >>> parameter = amda.get_data("imf", datetime.datetime(2000,1,1), datetime.datetime(2000,2,1))

diff --git a/docs/amda_catalogs.rst b/docs/amda_catalogs.rst
@@ -1,7 +1,7 @@
 .. _amda-catalogs-label:
 
 AMDA_Webservice Catalogs
--------------
+------------------------
 
 Description of AMDAs catalog objects and their representation in :mod:`speasy`. In :mod:`speasy`
 catalog metadata is stored as dictionary objects. The catalog's attributes are :

diff --git a/docs/amda_datasets.rst b/docs/amda_datasets.rst
@@ -1,5 +1,5 @@
 AMDA_Webservice Datasets
--------------
+------------------------
 
 Description of AMDAs dataset objects and their representation in :mod:`speasy`. In :mod:`speasy`
 dataset metadata is stored as dictionary objects. The dataset's attributes are :

diff --git a/docs/amda_example_1.rst b/docs/amda_example_1.rst
@@ -1,5 +1,5 @@
 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.
 

diff --git a/docs/amda_example_2.rst b/docs/amda_example_2.rst
@@ -1,5 +1,5 @@
 AMDA_Webservice Example 2: getting user defined parameter
-----------------------------------------------
+---------------------------------------------------------
 
 The following example illustrates how to access parameters defined on your user account within AMDA_Webservice.
 

diff --git a/docs/amda_example_3.rst b/docs/amda_example_3.rst
@@ -1,5 +1,5 @@
 AMDA_Webservice Example 3: listing available parameters
---------------------------------------------
+-------------------------------------------------------
 
 Simple example illustrating how to list available parameters, datasets and timetables.
 

diff --git a/docs/amda_example_4.rst b/docs/amda_example_4.rst
@@ -1,5 +1,5 @@
 AMDA_Webservice Example 4: getting timetables
-----------------------------------
+---------------------------------------------
 
 Download a public timetable.
 

diff --git a/docs/amda_example_get_catalog.rst b/docs/amda_example_get_catalog.rst
@@ -1,5 +1,5 @@
 AMDA_Webservice Example 7: getting catalogs
---------------------------------
+-------------------------------------------
 
 Download a public catalogs.
 

diff --git a/docs/amda_example_get_user_catalog.rst b/docs/amda_example_get_user_catalog.rst
@@ -1,5 +1,5 @@
 AMDA_Webservice Example 11: getting user catalogs
---------------------------------------
+-------------------------------------------------
 
 Downloading private catalogs.
 

diff --git a/docs/amda_example_get_user_timetable.rst b/docs/amda_example_get_user_timetable.rst
@@ -1,5 +1,5 @@
 AMDA_Webservice Example 10: getting user timetables
----------------------------------------
+---------------------------------------------------
 
 Downloading private timetables.
 

diff --git a/docs/amda_example_list_catalogs.rst b/docs/amda_example_list_catalogs.rst
@@ -1,9 +1,9 @@
 AMDA_Webservice Example 6: listing catalogs
---------------------------------
+-------------------------------------------
 
 Listing public catalogs.
 
-.. literalinclude:: ../examples/amda_list_public_catalogs.py
+.. literalinclude:: ../examples/amda_list_catalogs.py
 
 Output ::
 

diff --git a/docs/amda_example_list_timetables.rst b/docs/amda_example_list_timetables.rst
@@ -1,5 +1,5 @@
 AMDA_Webservice Example 5: listing timetables
-----------------------------------
+---------------------------------------------
 
 Listing public timetables.
 

diff --git a/docs/amda_example_list_user_catalogs.rst b/docs/amda_example_list_user_catalogs.rst
@@ -1,5 +1,5 @@
 AMDA_Webservice Example 9: listing user catalogs
--------------------------------------
+------------------------------------------------
 
 Listing private catalogs.
 

diff --git a/docs/amda_example_list_user_timetables.rst b/docs/amda_example_list_user_timetables.rst
@@ -1,5 +1,5 @@
 AMDA_Webservice Example 8: listing user timetables
----------------------------------------
+--------------------------------------------------
 
 Listing private timetables.
 

diff --git a/docs/amda_examples.rst b/docs/amda_examples.rst
@@ -1,5 +1,5 @@
 AMDA_Webservice Examples
--------------
+------------------------
 
 .. toctree::
    :maxdepth: 1

diff --git a/docs/amda_parameters.rst b/docs/amda_parameters.rst
@@ -1,5 +1,5 @@
 AMDA_Webservice Parameter
---------------
+-------------------------
 
 Description of AMDAs parameter objects and their representation in :mod:`speasy`. In :mod:`speasy`
 parameter metadata is stored as dictionary objects. The parameter's attributes are :

diff --git a/docs/amda_products.rst b/docs/amda_products.rst
@@ -1,5 +1,5 @@
 AMDA_Webservice Products
--------------
+------------------------
 
 List of AMDA_Webservice products.
 

diff --git a/docs/amda_timetables.rst b/docs/amda_timetables.rst
@@ -1,7 +1,7 @@
 .. _amda-timetables-label:
 
 AMDA_Webservice Timetables
----------------
+--------------------------
 
 
 

diff --git a/docs/cdaweb.rst b/docs/cdaweb.rst
@@ -0,0 +1,5 @@
+CDAWEB
+======
+
+.. toctree::
+   :maxdepth: 1
diff --git a/docs/dev_index.rst b/docs/dev_index.rst
@@ -6,7 +6,7 @@ Welcome to Speasy's developer documentation!
    :caption: Contents:
 
 Indices and tables
-==================
+------------------
 * :ref:`genindex`
 * :ref:`modindex`
 * :ref:`search`
diff --git a/docs/index.rst b/docs/index.rst
@@ -2,11 +2,11 @@ Welcome to Speasy's user documentation!
 =======================================
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 4
 
    readme
    installation
    user_modules
-
+   dev_index
 
 :doc:`Go to developers doc <dev_index>`
diff --git a/docs/sscweb.rst b/docs/sscweb.rst
@@ -0,0 +1,5 @@
+SSCWEB
+======
+
+.. toctree::
+   :maxdepth: 1
diff --git a/docs/user_modules.rst b/docs/user_modules.rst
@@ -1,5 +1,5 @@
 modules
-======
+=======
 
 .. toctree::
    :maxdepth: 4

diff --git a/speasy/config/__init__.py b/speasy/config/__init__.py
@@ -24,12 +24,23 @@ def _save_changes():
 class ConfigEntry:
     """Configuration entry class. Used to set and get configuration values.
 
-    :param key1: key 1
-    :type key1: str
-    :param key2: key 2
-    :type key2: str
-    :param default: default value
-    :type default: str
+    Attributes
+    ----------
+    key1: str
+        Module or category name
+    key2: str
+        Entry name
+    default: str
+        Default value given by ctor
+    env_var_name: str
+        Environment variable name to use to set this entry
+
+    Methods
+    -------
+    get:
+        Get entry current value
+    set:
+        Set entry value (could be env or file)
     """
 
     def __init__(self, key1: str, key2: str, default: str = ""):
@@ -41,8 +52,10 @@ def __init__(self, key1: str, key2: str, default: str = ""):
     def get(self):
         """Get configuration entry value. If a default is not provided then raise :class:`~speasy.config.exceptions.UndefinedConfigEntry`.
 
-        :return: configuration value
-        :rtype: str
+        Returns
+        -------
+        str:
+            configuration value
         """
         if self.env_var_name in os.environ:
             return os.environ[self.env_var_name]

diff --git a/speasy/products/catalog.py b/speasy/products/catalog.py
@@ -23,6 +23,9 @@ class Event(DateTimeRange):
     meta : dict
             Additional event data
 
+    Methods
+    -------
+
     Notes
     -----
     This class support the same operations as a speasy.common.datetime_range.DateTimeRange.
@@ -54,6 +57,14 @@ class Catalog:
         Catalog name
     meta : dict
         All additional Catalog meta data
+
+    Methods
+    -------
+    append:
+        Append an Event or a list of Event to the end of the Catalog
+    pop:
+        Remove and return Event at index (default last)
+
     Examples
     --------
     >>> my_catalog=Catalog(name='MyCatalog', meta={'tags':['demo', 'docstrings']}, events=[])