Documentation: Enhanced, developer's version

README-development.md → README-developers.md

 # The DACE api.
 
-This is the **development** documentation.
+This is the **developers**' documentation.
 
 ## Install ( from the requirements )
 
-This section describes how to install properly ( using **poetry** ) the dace api and required modules in order to
-**debug** it, **add** in or **code** **modules**.
+This section describes how to install properly ( using **poetry** ) the _dace-query_ package and all the required
+modules in order to **debug** it, **add** in or **code** **modules**.
 
 ```shell
-# This will create a poetry environment and install in the required modules 
+# This will create a poetry environment and install in it the required modules 
 poetry install
 ```
 
 ## Test validation
 
-This section describes how to run tests properly.   
+This section describes how to run tests properly.  
 There are two type of test :
 
-* pytest : python test
+* **pytest :** python test
 
 ```shell
 # This will run python test which are stored under the /tests folder
 poetry run pytest
 ```
 
-* doctest : docstring test
+* **doctest :** docstring test
 
 ```shell
 # This will execute docstring tests and the result output will be store under /docs/build/doctest 
 cd docs && make doctest
 ```
 
+---
+**Note :**
+
+In order to run the tests correctly, it is necessary to have the following two files correctly defined under
+the [`tests`](./tests) folder :
+
+* _config.ini_ ( where endpoints are the developments endpoints )
+* _dev.dacerc_ ( where the api key is that of a particular privileged user )
+
+---
+
 ## Package generation
 
-This section describes to generate properly ( using **poetry** ) the package.
+This section describes how to generate properly ( using **poetry** ) the package.
+
+**Important steps to take before generating & uploading the package**
+
+1. Update the package version ( **tool.poetry.version** ) in the [`pyproject.toml`](./pyproject.toml) file, then execute `poetry lock`
+2. Edit the [`changelogs.rst`](./docs/source/changelogs.rst) file
+3. Commit and push every change & tag the commit ( using **git** )
 
 ```shell
 # This will create a tar.gz and .whl package under /dist
-# TEST_PYPI_TOKEN is the token generated by https://test.pypi.org
 poetry build
 poetry run twine check dist/*.tar.gz
-poetry source add pypi-test https://test.pypi.org/legacy/
-poetry config pypi-token.pypi-test $TEST_PYPI_TOKEN
-poetry publish --repository pypi-test
 
+# .. Publish the package on https://test.pypi.org (in case of development release)
+# TEST_PYPI_TOKEN is the token generated by https://test.pypi.org
+# poetry source add pypi-test https://test.pypi.org/legacy/
+# poetry config pypi-token.pypi-test $TEST_PYPI_TOKEN
+# poetry publish --repository pypi-test
+
+# .. Publish the package on https://pypi.org
+# PYPI_TOKEN is the token generated by https://pypi.org
+poetry config pypi-token.pypi $PYPI_TOKEN
+poetry publish
 ```
 
 ## Documentation initialization
 
-This section describe how to initialize (for the 1st time) the documentation folder
+This section describes how to initialize **for the 1st time** the documentation folder.
 
 ```shell
 # This will generate the docs folder containing init files
 sphinx-quickstart docs/
-
-
 ```
 
 ## Documentation generation ( locally )
@@ -66,7 +87,7 @@ This section describes how to generate the documentation.
 cd docs && make html
 ```
 
-and cleaning documentation can be done using :
+and locally clean the documentation is done using :
 
 ```shell
 # This will remove anything under docs/build/
@@ -85,23 +106,10 @@ In case new modules need to be added in the documentation, _dace.rst_ must be re
 
 ## Documentation publication
 
-This section describes how to compile and publish the dace-api documentation using https://readthedocs.io.
+This section describes how to compile and publish the dace-api documentation using https://readthedocs.org
 
 1. Commit the changes
 2. Build and publish the package
-3. Log in to readthedocs.io
-4. Add the project using http credentials if not already done
+3. Log in to https://readthedocs.org
+4. Add the project ( if not already done )
 5. Compile latest version of documentation
-
-## Update the package version
-
----
-**Important note :**
-
-Only change the pyproject.toml tool.poetry.version value and then run
-
-```shell
-poetry lock
-```
-
----

README.rst

@@ -3,12 +3,12 @@ dace-query
 
 Description
 ***********
-The dace-query lets easily query DACE and access public and private data using a simple utility tool.
+The dace-query package lets easily query DACE and access public and private data using a simple utility tool.
 
 Installation
 ************
 
-The dace-query is available on PyPi and can be installed using `pip <https://pypi.org/project/pip/>`_ or `conda <https://www.anaconda.com>`_:
+The dace-query package is available on PyPi and can be installed using `pip <https://pypi.org/project/pip/>`_ or `conda <https://www.anaconda.com>`_:
 
 
 .. code-block:: bash
@@ -29,7 +29,7 @@ The dace-query is available on PyPi and can be installed using `pip <https://pyp
     # Finally, install using anaconda pip
     pip install dace-query
 
-Make sure the API is installed correctly :
+Make sure the package is installed correctly :
 
 .. code-block:: python
 

dace_query/tess/tess.py

@@ -19,7 +19,7 @@ class TessClass:
     The tess class.
     Use to retrieve data from the tess module.
 
-    **A tess instance is already provided, to uses it :**
+    **A tess instance is already provided, to use it :**
 
     >>> from dace_query.tess import Tess
     """

docs/source/changelogs.rst

-1.0.0
+dev (1.1.0)
+***********
+
+* Cheops module
+    * List data products for a specified visit
+
+1.0.1
 *****
 
 **The first public release of the dace-query package**

docs/source/dace_introduction.rst

@@ -3,12 +3,12 @@ dace-query
 
 Description
 ***********
-The dace-query lets easily query DACE and access public and private data using a simple utility tool.
+The dace-query package lets easily query DACE and access public and private data using a simple utility tool.
 
 Installation
 ************
 
-The dace-query is available on PyPi and can be installed using `pip <https://pypi.org/project/pip/>`_ or `conda <https://www.anaconda.com>`_ :
+The dace-query package is available on PyPi and can be installed using `pip <https://pypi.org/project/pip/>`_ or `conda <https://www.anaconda.com>`_ :
 
 
 .. code-block:: bash
@@ -29,7 +29,7 @@ The dace-query is available on PyPi and can be installed using `pip <https://pyp
     # Finally, install using anaconda pip
     pip install dace-query
 
-Make sure the API is installed correctly :
+Make sure the package is installed correctly :
 
 .. code-block:: python
 

docs/source/query_options.rst

@@ -76,8 +76,8 @@ These two filters can be applied to *string* type parameters.
 
 
 
-equal - notEqual
-----------------
+equal - not equal
+-----------------
 
 This filter filters the chosen parameter if it is equal or not to the value sought.
 

pyproject.toml

 [tool.poetry]
 name = "dace-query"
-version = "1.0.1"
+version = "1.1.0"
 description = "The dace-query lets easily query DACE and access public and private data using a simple utility tool."
 authors = ["dace-team <dace-support@unige.ch>"]
 readme = "README.rst"