Renata/docs (#563)

* docs

* split network file

* updates conf file

* docs

* route choice model docs

* .

* Update route_choice.py

* docs

* .

* .

* change folder structure

* .

* .

* .

* rename folders

* linting

* rename files

* .

* .

* .

* adds modules references in examples

* .

* adds new sections in docs

* docs

* .

* Update 7-project_components.rst

* .

* docs

* removes data_model tables

* nodes docs

* links and zones docs

* docs

* .

* rename folder

* .

* Update table_documentation.py

* Create datamodel.rst.template

* removes geopandas from some examples

* fixes imports

* update docs

* update docs

* Update route_choice.py

* .

* add doctest strings

* .

* .

* .

* Update project_components.rst

* modifies doctest ellipsis

* print test string

* modify switcher

* change project structure

* changes

* Update plot_subarea_analysis.py

* Update project_components.rst

* typos, tests, and admonitions

* admonitions

---------

Co-authored-by: pveigadecamargo <[email protected]>

.github/workflows/documentation.yml

@@ -46,10 +46,11 @@ jobs:
     - name: Test docstrings
       run: |
         python -m pytest --doctest-modules aequilibrae/log.py aequilibrae/parameters.py aequilibrae/paths/vdf.py
+        python -m pytest docs/source/modeling_with_aequilibrae/project_pieces --doctest-glob=*.rst
 
     - name: Build documentation
       run: |
-        jupyter nbconvert --to rst docs/source/validation_benchmarking/IPF_benchmark.ipynb
+        jupyter nbconvert --to rst docs/source/useful_information/validation_benchmarking/IPF_benchmark.ipynb
         sphinx-build -M latexpdf docs/source docs/source/_static
         sphinx-build -b html docs/source docs/build
         python3 -m zipfile -c AequilibraE.zip docs/build

.gitignore

@@ -2,6 +2,11 @@
 _build
 _static
 _templates
+docs/source/sg_execution_times.rst
+docs/source/_auto_examples
+docs/source/api/generated
+docs/source/modeling_with_aequilibrae/project_database/data_model
+docs/source/modeling_with_aequilibrae/transit_database/data_model
 
 # User-specific stuff:
 .idea/**/workspace.xml

aequilibrae/matrix/aequilibrae_matrix.py

@@ -93,6 +93,8 @@ def save(self, names=(), file_name=None) -> None:
 
         :Arguments:
             **names** (:obj:`tuple(str)`, *Optional*): New names for the matrices. Required if working with OMX files
+
+            **file_name** (:obj:`str`, *Optional*): Local path to the matrix file
         """
         if file_name is not None:
             cores = names if len(names) else self.names
@@ -293,21 +295,22 @@ def create_from_omx(
         Creates an AequilibraeMatrix from an original OpenMatrix
 
         :Arguments:
-            **file_path** (:obj:`str`): Path for the output AequilibraEMatrix
+            **file_path** (:obj:`str`): Path for the output AequilibraeMatrix
 
             **omx_path** (:obj:`str`): Path to the OMX file one wants to import
 
-            **cores** (:obj:`list`): List of matrix cores to be imported
+            **cores** (:obj:`list`, *Optional*): List of matrix cores to be imported
 
-            **mappings** (:obj:`list`): List of the matrix mappings (i.e. indices, centroid numbers) to be imported
+            **mappings** (:obj:`list`, *Optional*): List of the matrix mappings (i.e. indices, centroid numbers)
+            to be imported
 
-            **robust** (:obj:`bool`, *Optional*): Boolean for whether AequilibraE should try to adjust the names for cores
-            and indices in case they are too long. Defaults to True
+            **robust** (:obj:`bool`, *Optional*): Boolean for whether AequilibraE should try to adjust the names
+            for cores and indices in case they are too long. Defaults to ``True``
 
             **compressed** (:obj:`bool`, *Optional*): Boolean for whether we should compress the output matrix.
             Not yet implemented
 
-            **memory_only** (:obj:`bool`, *Optional*): Whether you want to keep the matrix copy in memory only. Defaults to True
+            **memory_only** (:obj:`bool`, *Optional*): Whether you want to keep the matrix copy in memory only. Defaults to ``True``
 
         """
 
@@ -405,7 +408,7 @@ def create_from_trip_list(self, path_to_file: str, from_column: str, to_column:
 
             **from_column** (:obj:`str`): trip list file column containing the origin zones numbers
 
-            **from_column** (:obj:`str`): trip list file column containing the destination zones numbers
+            **to_column** (:obj:`str`): trip list file column containing the destination zones numbers
 
             **list_cores** (:obj:`list`): list of core columns in the trip list file
 
@@ -840,7 +843,7 @@ def load(self, file_path: str):
             self.__load_aem__()
 
     def is_omx(self):
-        """Returns ``True`` if matrix data source is OMX, False otherwise"""
+        """Returns ``True`` if matrix data source is OMX, ``False`` otherwise"""
         return self.__omx
 
     def computational_view(self, core_list: List[str] = None):
@@ -920,7 +923,7 @@ def copy(
             **output_name** (:obj:`str`): Name of the new matrix file.
             If none is provided, returns a copy in memory only
 
-            **cores** (:obj:`list`):List of the matrix cores to be copied
+            **cores** (:obj:`list`): List of the matrix cores to be copied
 
             **names** (:obj:`list`, *Optional*): List with the new names for the cores. Defaults to current names
 
@@ -1044,7 +1047,7 @@ def columns(self) -> np.ndarray:
 
     def nan_to_num(self):
         """
-        Converts all NaN values in all cores in the computational view to zeros
+        Converts all ``NaN`` values in all cores in the computational view to zeros
 
         .. code-block:: python
 

aequilibrae/parameters.py

@@ -6,16 +6,24 @@
 
 
 class Parameters:
-    """Global parameters module
+    """Global parameters module.
+
+    Parameters are used in many procedures, and are often defined in the ``parameters.yml`` file ONLY.
 
-    Parameters are used in many procedures, and are often defined only in the parameters.yml file ONLY
     Parameters are organized in the following groups:
 
     * assignment
     * distribution
+    * network
+      * links
+      * modes
+      * nodes
+      * osm
+      * gmns
+    * osm
     * system
-    * report zeros
-    * temp directory
+
+    Please observe that OSM information handled on network is not the same on the OSM group.
 
     .. code-block:: python