Merge pull request #381 from Deltares/docs/354-extend-general-overvie…

…w-documentation Docs/354 extend general overview documentation
Deltares · Mar 25, 2024 · 3c7513a · 3c7513a
2 parents 40976c7 + fa0a90d
commit 3c7513a
Show file tree

Hide file tree

Showing 18 changed files with 64 additions and 1,327 deletions.
diff --git a/docs/.gitignore b/docs/.gitignore
@@ -0,0 +1,3 @@
+# Directories created during build of SPHINX
+build/**
+docs/**
diff --git a/docs/_diagrams/ra2ce_analysis.drawio b/docs/_diagrams/ra2ce_analysis.drawio
diff --git a/docs/_diagrams/ra2ce_analysis.png b/docs/_diagrams/ra2ce_analysis.png
diff --git a/docs/_diagrams/ra2ce_analysis_class_diagram.drawio.png b/docs/_diagrams/ra2ce_analysis_class_diagram.drawio.png
diff --git a/docs/_diagrams/ra2ce_network.drawio b/docs/_diagrams/ra2ce_network.drawio
diff --git a/docs/_diagrams/ra2ce_network.png b/docs/_diagrams/ra2ce_network.png
diff --git a/docs/_diagrams/ra2ce_network_class_diagram.drawio.png b/docs/_diagrams/ra2ce_network_class_diagram.drawio.png
diff --git a/docs/_diagrams/ra2ce_overview.drawio b/docs/_diagrams/ra2ce_overview.drawio
diff --git a/docs/_diagrams/ra2ce_package_overview.drawio.png b/docs/_diagrams/ra2ce_package_overview.drawio.png
diff --git a/docs/_diagrams/ra2ce_v0_3_0.drawio b/docs/_diagrams/ra2ce_v0_3_0.drawio
diff --git a/docs/conf.py b/docs/conf.py
@@ -22,6 +22,7 @@
 import sys
 from distutils.dir_util import copy_tree
 import sphinx_autosummary_accessors
+from pathlib import Path
 
 # This is not needed
 sys.path.insert(0, os.path.abspath(".."))
@@ -48,9 +49,21 @@ def remove_dir_content(path: str) -> None:
     remove_dir_content("build")
 if os.path.isdir("_examples"):
     remove_dir_content("_examples")
+
 os.makedirs("_examples")
 copy_tree("../examples", "_examples")
 
+if os.path.isdir("docs"):
+    remove_dir_content("docs")
+
+_src_diagrams = "../docs/_diagrams/"
+_dst_diagrams = "docs/_diagrams/"
+os.makedirs(_dst_diagrams)
+for _img_file in os.listdir(_src_diagrams):
+    if not _img_file.endswith(".png"):
+        continue
+    shutil.copy((_src_diagrams + _img_file), (_dst_diagrams + _img_file))
+
 # -- General configuration ---------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.

diff --git a/...chnical_documentation/_generated/ra2ce.ra2ce_handler.Ra2ceHandler.configure.rst b/...chnical_documentation/_generated/ra2ce.ra2ce_handler.Ra2ceHandler.configure.rst
diff --git a/...ical_documentation/_generated/ra2ce.ra2ce_handler.Ra2ceHandler.run_analysis.rst b/...ical_documentation/_generated/ra2ce.ra2ce_handler.Ra2ceHandler.run_analysis.rst
diff --git a/docs/technical_documentation/analysis_package.rst b/docs/technical_documentation/analysis_package.rst
@@ -0,0 +1,8 @@
+.. _analysis_package:
+
+============
+Analysis
+============
+
+.. include:: ../../ra2ce/analysis/README.md
+   :parser: myst_parser.sphinx_
diff --git a/docs/technical_documentation/technical_documentation.rst b/docs/technical_documentation/technical_documentation.rst
@@ -7,4 +7,8 @@ Technical Documentation
    :caption: Table of Contents
    :maxdepth: 2
 
-   network_package
+   network_package
+   analysis_package
+
+.. include:: ../../ra2ce/README.md
+   :parser: myst_parser.sphinx_
diff --git a/ra2ce/README.md b/ra2ce/README.md
@@ -0,0 +1,29 @@
+# RA2CE
+
+## Ra2ce semantics
+
+- `ra2ce` is a [package](https://packaging.python.org/en/latest/tutorials/packaging-projects/),
+- everything else with an `__init__.py` is a subpackage (often written as (sub-)package).
+- single `.py` files are [modules](https://docs.python.org/3/tutorial/modules.html),
+- from a business perspective an `analysis` might be a module, but technically it can be implemented either as a (subpackage) or a module.
+
+## Structure description
+
+This package is divided into different (sub-)packages, the most relevants being the following:
+
+- `network`, this (sub-)package contains the logic to retrieve a normalized data structure capable of representing all the required properties of a network for its later analysis.
+- `analysis`, this (sub-)package is responsible to execute an analysis (`direct` or `indirect`) for the given network.
+- `runners`, this (sub-)package encapsulates the logic to automatize an analysis of a ra2ce model.
+
+Other (sub-)packages carry a more 'supporting' role, such as:
+
+- `common`, a (sub-)package mostly contaning generic definitions as protocols (`typing.Protocol`) to be used across the whole project.
+- `configuration`, a subpackage responsible to parse the ra2ce `.ini` configuration files (for network and analysis) into their corresponding dataclasses. It is worth mentioning this subpackage is explicitely outside `common` to avoid circular dependencies with the `analysis` and `network` subpackages.
+
+## General class overview
+
+A general overview of the package relationships can be seen in the following diagram.
+
+| ![ra2ce_package_overview.drawio.png](/docs/_diagrams/ra2ce_package_overview.drawio.png)| 
+|:--:| 
+| *Ra2ce package overview* |
diff --git a/ra2ce/analysis/README.md b/ra2ce/analysis/README.md
@@ -9,7 +9,7 @@ Each analysis should comply to the `AnalysisProtocol`.
 ## General class overview
 The following diagram describes the relations between the most relevant entities of the `ra2ce.analysis` (sub-)package.
 
-| ![ra2ce_analysis.jpg](../../docs/_diagrams/ra2ce_analysis.png)| 
+| ![ra2ce_analysis_class_diagram.drawio.png](/docs/_diagrams/ra2ce_analysis_class_diagram.drawio.png)| 
 |:--:| 
 | *Ra2ce analysis overview* |
 

diff --git a/ra2ce/network/README.md b/ra2ce/network/README.md
@@ -1,19 +1,16 @@
 # Network
 
-In this package you will find all logic required to load network data from diverse sources (file or web based). 
+In this (sub-)package you will find all logic required to load network data from diverse sources (file or web based). 
 
-The configuration to be used to load a network is usually an `.ini` file. This file is later represented as a `NetworkConfigData` object that can as well be directly initialized via code (`network_config_data` (sub)package).
+The configuration to be used to load a network is usually an `.ini` file. This file is later represented as a `NetworkConfigData` object that can as well be directly initialized via code (`network_config_data` (sub-)package).
 
-The different sources to generate a network are handled through our own network wrappers (`NetworkWrapperProtocol`) in the `network_wrappers` (sub)package.
+The different sources to generate a network are handled through our own network wrappers (`NetworkWrapperProtocol`) in the `network_wrappers` (sub-)package.
 
 
 ## General class overview
 
 The following diagram describes the relations between the most relevant entities of the `ra2ce.network` (sub-)package.
 
-| ![ra2ce_network.jpg](../../docs/_diagrams/ra2ce_network.png)| 
+| ![ra2ce_network_class_diagram.drawio.png](/docs/_diagrams/ra2ce_network_class_diagram.drawio.png)| 
 |:--:| 
-| *Ra2ce network overview* |
-
-Add class diagram
-Add flowchart diagram of loading a diagram
+| *Ra2ce network overview* |