Merge pull request #84 from ioannis-vm/docs

Update Docs.
NHERI-SimCenter · Dec 10, 2024 · 1b491c1 · 1b491c1
2 parents 5d7e9af + d79cffc
commit 1b491c1
Show file tree

Hide file tree

Showing 32 changed files with 585 additions and 1,880 deletions.
diff --git a/README.md b/README.md
@@ -46,8 +46,6 @@ Detailed documentation of the available methods and their use is available at ht
 
 ## Installation
 
-### For users
-
 `pelicun` is available at the [Python Package Index (PyPI)](https://pypi.org/project/pelicun/). You can simply install it using `pip` as follows:
 
 ```shell
@@ -62,51 +60,10 @@ pip install pelicun==2.6.0
 
 Note that 2.6.0 is the last minor version before the v3.0 release. Other earlier versions can be found [here](https://pypi.org/project/pelicun/#history).
 
-### For contributors
-
-Developers are expected to fork and clone this repository, and install their copy in development mode.
-Using a virtual environment is highly recommended.
-
-```shell
-# Clone the repository:
-git clone https://github.com/<user>/pelicun
-cd pelicun
-# Switch to the appropriate branch, if needed.
-# git checkout <branch>
-
-# Install pelicun:
-# Note: don't forget to activate the corresponding environment.
-python -m pip install -e .[development]
-
-```
-
-Contributions are managed with pull requests.
-It is required that contributed code is [PEP 8](https://peps.python.org/pep-0008/) compliant, does not introduce linter warnings and includes sufficient unit tests so as to avoid reducing the current coverage level.
-
-The following lines implement the aforementioned checks.
-`flake8`, `pylint` and `pytest` can all be configured for use within an IDE.
-```shell
-
-cd <path-to>/pelicun
-export PYTHONPATH=$PYTHONPATH:$(pwd)
-
-# Linting with flake8:
-flake8 pelicun
-
-# Linting with pylint:
-pylint pelicun
-
-# Type checking with mypy:
-mypy pelicun --no-namespace-packages
-
-# Running the tests:
-python -m pytest pelicun/tests --cov=pelicun --cov-report html
-# Open `htmlcov/index.html`in a browser to see coverage results.
-
-```
-
-Feel free to [open an issue](https://github.com/NHERI-SimCenter/pelicun/issues/new/choose) if you encounter problems setting up the provided development environment.
+## Documentation and usage examples
 
+The documentation for pelicun can be accessed [here](https://NHERI-SimCenter.github.io/pelicun/).
+It includes information for users, instructions for developers and usage examples.
 
 ## Changelog
 

diff --git a/doc/source/_static/hide_empty_pre.js b/doc/source/_static/hide_empty_pre.js
@@ -0,0 +1,13 @@
+document.addEventListener("DOMContentLoaded", function() {
+    document.querySelectorAll('div.nboutput.docutils.container').forEach(function(div) {
+        // Our objective is to hide all `div` elements of which all
+        // children elements only contain whitespace.
+        // This remedies the nbsphinx issue where an extra newline was
+        // added to each line in the code block output.
+        let isEmpty = Array.from(div.children).every(child => !child.textContent.trim());
+
+        if (isEmpty) {
+            div.style.display = 'none';
+        }
+    });
+});
diff --git a/doc/source/conf.py b/doc/source/conf.py
@@ -60,6 +60,7 @@
 html_static_path = ['_static']
 
 html_css_files = ['css/custom.css']
+html_js_files = ['hide_empty_pre.js']
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.

diff --git a/doc/source/developer_guide/development_environment.rst b/doc/source/developer_guide/development_environment.rst
@@ -8,6 +8,18 @@ Setting up a development environment
    We recommend creating a dedicated `virtual environment <https://docs.python.org/3/library/venv.html>`_ for your pelicun development environment.
    See also `conda <https://docs.conda.io/en/latest/>`_ and `mamba <https://mamba.readthedocs.io/en/latest/>`_, two widely used programs featuring environment management.
 
+Clone the repository::
+
+  git clone --recurse-submodules https://github.com/NHERI-SimCenter/pelicun
+
+Pelicun uses the SimCenter `DamageAndLossModelLibrary <https://github.com/NHERI-SimCenter/DamageAndLossModelLibrary>`_ as a submodule.
+In the above, ``recurse-submodules`` ensures that all files of that repository are also obtained.
+
+.. tip::
+
+   If you are planning to contribute code, please `fork the repository <https://github.com/NHERI-SimCenter/pelicun/fork>`_ and clone your own fork.
+
+
 Install pelicun in editable mode with the following command issued from the package's root directory::
 
   python -m pip install -e .[development]

diff --git a/doc/source/examples/index.rst b/doc/source/examples/index.rst
@@ -14,59 +14,29 @@ Pelicun examples are listed in the following index.
    Increasing the set of examples is a very high priority.
    Please come back soon!
 
-Complete list
--------------
-
 +-----------+---------------------------------------------------------+
 |Example    |Description                                              |
 +===========+=========================================================+
-|`E1`_      |This example demonstrates the seismic performance        |
-|           |assessment of a steel moment frame structure using the   |
-|           |FEMA P-58 methodology.                                   |
+|`E1`_      |Example of a simple assessment involving a single loss   |
+|           |function. The example and associated input files can be  |
+|           |easily extended to include more loss functions and input |
+|           |demands.                                                 |
++-----------+---------------------------------------------------------+
+|`E2`_      |Example validating the estimated damage state            |
+|           |probabilities of a single component.                     |
++-----------+---------------------------------------------------------+
+|`E3`_      |A loss assessment combining fragility-based damage       |
+|           |consequences and loss functions.                         |
 +-----------+---------------------------------------------------------+
-
-Grouped by feature
-------------------
-
-The following sections group the examples above based on the specific features they illustrate, helping you pick the ones most relevant to what you are looking for.
-
-.. dropdown:: Asset type
-
-   +------------------------------------------------------+---------------------------------------------------------+
-   |Feature                                               |Examples                                                 |
-   +======================================================+=========================================================+
-   |Building                                              |`E1`_                                                    |
-   +------------------------------------------------------+---------------------------------------------------------+
-
-.. dropdown:: Demand Simulation
-
-   +------------------------------------------------------+---------------------------------------------------------+
-   |Feature                                               |Examples                                                 |
-   +======================================================+=========================================================+
-   |:ref:`Model calibration <fo_calibration>`             |`E1`_                                                    |
-   +------------------------------------------------------+---------------------------------------------------------+
-   |:ref:`RID|PID inference <fo_pidrid>`                  |`E1`_                                                    |
-   +------------------------------------------------------+---------------------------------------------------------+
-   |:ref:`Sample expansion <fo_sample_expansion>`         |`E1`_                                                    |
-   +------------------------------------------------------+---------------------------------------------------------+
-
-
-.. dropdown:: Loss estimation
-
-   +------------------------------------------------------+---------------------------------------------------------+
-   |Feature                                               |Examples                                                 |
-   +======================================================+=========================================================+
-   |:ref:`Loss maps <fo_loss_maps>`                       |`E1`_                                                    |
-   +------------------------------------------------------+---------------------------------------------------------+
-   |:ref:`Active decision variables <fo_active_dvs>`      |`E1`_                                                    |
-   +------------------------------------------------------+---------------------------------------------------------+
-   |:ref:`Loss aggregation <fo_loss_aggregation>`         |`E1`_                                                    |
-   +------------------------------------------------------+---------------------------------------------------------+
 
 .. toctree::
    :maxdepth: 1
    :hidden:
 
    notebooks/example_1.pct.py
+   notebooks/example_2.pct.py
+   notebooks/example_3.pct.py
 
 .. _E1: notebooks/example_1.pct.py
+.. _E2: notebooks/example_2.pct.py
+.. _E3: notebooks/example_3.pct.py