Merge pull request #304 from Deltares/chore/188-replace-geopy-usage-w…

…ith-geopandas

docs: Added new chapter to refer to design principles. Reduced number…

docs/collaboration/collaboration.rst

@@ -6,6 +6,8 @@ Contributing
 Contributions are welcome, and they are greatly appreciated! Every little bit
 helps, and credit will always be given.
 
+In addition to the content of this file, please check our :ref:`design_principles` subchapter.
+
 
 Guidelines
 -----------------------
@@ -148,3 +150,11 @@ If you are proposing a feature:
 * Remember that this is a volunteer-driven project, and that contributions
   are welcome :)
 
+
+.. toctree::
+   :caption: Table of Contents
+   :maxdepth: 1
+   :hidden:
+
+   design_principles
+   implementation_decisions

docs/collaboration/design_principles.rst

@@ -0,0 +1,78 @@
+.. _design_principles:
+
+Design principles
+=================
+
+Throughout RA2CE different design choices are made to achieve a software as easy as possible to understand whilst hosting the domain knowledge of our experts. 
+
+Code standards
+---------------
+
+In general, we adhere to the `Zen of Python <https://peps.python.org/pep-0020/#id3>`_ and we use the `Google convention <https://google.github.io/styleguide/pyguide.html>`_ as a base for our coding standards. 
+Those points where we differ from the `Google convention` are documented below. We consider this document to be a living document, so it is subject to discussion and potential changes.
+
+When we talk about normalization we refer to standardizing how we name, describe, reference and use the following items:
+
+- a package (folder),
+- a module (file),
+- a class,
+- a method,
+- a parameter,
+- a property,
+- a variable,
+
+Code formatting happens in its majority with a Github workflow which is enforced after each succesful pull-request merge to main. This can be at any time locally done running the line:
+
+.. code-block:: python
+    
+    poetry run isort . && poetry run black .
+
+Naming conventions
+^^^^^^^^^^^^^^^^^^
+In general we use the following standards:
+
+- `PascalCase <https://en.wiktionary.org/wiki/Pascal_case#English>`_, for class names.
+- `snake_case <https://en.wikipedia.org/wiki/Snake_case>`_, for the rest.
+
+
+Although in Python 'private' and 'public' is a vague definition, we often use the underscore symbol `_` to refer to objects that are not meant to be used outside the context where they were defined. For instance:
+
+- We underscore method's names when they are not meant to be used outisde their container class.
+- In addition, we underscore the variables defined within a method to (visually) differenciate them from the input arguments (parameters):
+
+.. code-block:: python
+
+    def example_method(param_a: float, param_b: float) -> float:
+        _sum = param_a + param_b
+        return _sum
+
+
+Module (file) content
+^^^^^^^^^^^^^^^^^^^^^
+
+In general:
+
+- One file consists of one (and only one) class.
+- The file containing a class will have the same name (snake case for the file, upper camel case for the class).
+
+Some exceptions:
+
+- An auxiliar dataclass might be eventually defined in the same file as the only class using (and referencing) it.
+- Test classes may contain mock classes when they are only to be used within said test-file.
+
+
+Describing an item
+^^^^^^^^^^^^^^^^^^
+
+- Packages can be further describe with `README.md` files.
+- Modules are described with docstrings using the `google docstring convention <https://gist.github.com/redlotus/3bc387c2591e3e908c9b63b97b11d24e>`_
+- We prefer explicit over implicit declaration.
+    - Use of `type hinting <https://docs.python.org/3/library/typing.html>`_.
+- Classes are described with docstrings when required, its properties also have descriptive names and have explicit types using `type hints <https://docs.python.org/3/library/typing.html>`_.
+- Methods contain a clear descriptive name, its arguments (parameters) contain `type hints <https://docs.python.org/3/library/typing.html>`_ and in case it is a 'public' method its signature has a description following the `google docstrings <https://google.github.io/styleguide/pyguide.html>`_ formatting.
+
+
+Protocols over Base classes.
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+We prefer using `protocols <https://docs.python.org/3/library/typing.html#typing.Protocol>`_ over `base classes <https://docs.python.org/3/library/abc.html>`_ (abstract class) to enforce the `Single Responsibility Principle <https://en.wikipedia.org/wiki/Single_responsibility_principle>`_ as much as possible.

docs/collaboration/implementation_decisions.rst

@@ -0,0 +1,14 @@
+.. _implementation_decisions:
+
+Implementation decisions
+========================
+
+Some concrete cases require to be highlighted to avoid creating related issues and specifying the concrete direction we want to go on as a team.
+
+Replacing Geopy with Geopandas
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+We tried replacing `geopy <https://geopy.readthedocs.io/en/stable/>`_ with similar functionality of `Geopandas <https://geopandas.org/en/stable/>`_. 
+However, this did not seem to be a valid alternative as the accuracy and simplicity of geopy outweights the benefit of replacing it with similar extensive logic as can be seen in this `example <https://autogis-site.readthedocs.io/en/2019/notebooks/L2/calculating-distances.html>`_. 
+
+.. tip:: 
+    This topic was handled in issue `188 <https://github.com/Deltares/ra2ce/issues/188>`_

docs/conf.py

@@ -44,6 +44,8 @@ def remove_dir_content(path: str) -> None:
 
 # NOTE: the examples/ folder in the root should be copied to docs/_examples after running sphinx
 # # -- Copy notebooks to include in docs -------
+if os.path.isdir("build"):
+    remove_dir_content("build")
 if os.path.isdir("_examples"):
     remove_dir_content("_examples")
 os.makedirs("_examples")
@@ -64,6 +66,7 @@ def remove_dir_content(path: str) -> None:
     "sphinx.ext.viewcode",
     "sphinx.ext.githubpages",
     "sphinx.ext.napoleon",
+    "sphinx.ext.autosectionlabel",
     "sphinx.ext.autosummary",
     "sphinx_autosummary_accessors",
     "nbsphinx",
@@ -242,4 +245,4 @@ def remove_dir_content(path: str) -> None:
 # Allow errors in notebooks
 nbsphinx_allow_errors = True
 # Do not execute the scripts during the build process.
-nbsphinx_execute = 'never'
+nbsphinx_execute = "never"

docs/index.rst

@@ -20,11 +20,8 @@ Or navigate directly to another section:
 
    overview
    installation/installation
-   installation/docker_user_guide
    user_guide/user_guide
    examples/examples
-   network_module/network_module
-   analysis_module/analysis_module
    collaboration/collaboration
    changelog_wrapper
 

docs/installation/installation.rst

@@ -48,3 +48,12 @@ In this environment you will find all our available examples as well as the poss
 
 - Our `ra2ce jupyter-binder <https://mybinder.org/v2/gh/Deltares/ra2ce/jupyter-binder>`_ environment.
 - More about `binder <https://mybinder.readthedocs.io/en/latest/>`_.
+
+
+
+.. toctree::
+   :caption: Table of Contents
+   :maxdepth: 2
+   :hidden:
+
+   docker_user_guide.rst

docs/overview.rst

@@ -89,15 +89,15 @@ Overview
 
 .. toctree::
    :caption: Table of Contents
-   :maxdepth: 2
+   :maxdepth: 1
    :hidden:
 
    about/about.rst
    installation/installation.rst
    examples/examples.rst
    network_module/network_module.rst
    analysis_module/analysis_module.rst 
+   collaboration/collaboration.rst
    technical_documentation/technical_documentation.rst
    faq/faq.rst
-   collaboration/collaboration.rst
    publications/publications.rst