docs: add auxiliary example notebooks and revise structure

Author: Fahrettin Kuran

.gitignore

@@ -69,7 +69,7 @@ instance/
 .scrapy
 
 # Sphinx documentation
-docs/_build/
+doc/_build/
 
 # PyBuilder
 .pybuilder/
@@ -135,6 +135,7 @@ venv/
 ENV/
 env.bak/
 venv.bak/
+quaket_env/
 
 # Spyder project settings
 .spyderproject

doc/conf.py

@@ -11,26 +11,34 @@
 author = 'GEM Foundation and Électricité de France'
 release = '0.1'
 
-
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
+import os
+import sys
+import shutil
+
 extensions = [
   'sphinx.ext.todo',
   'sphinx.ext.coverage',
   'sphinx.ext.mathjax',
   'sphinx.ext.viewcode',
   'sphinx.ext.githubpages',
-  'recommonmark',
-  'nbsphinx'
+  'sphinx_rtd_theme',
+  'myst_parser',
+  'nbsphinx',
+  'nbsphinx_link',
 ]
 
+nbsphinx_allow_errors = True
+nbsphinx_execute = 'never'
+
 templates_path = ['_templates']
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', '**.ipynb_checkpoints']
 
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
-html_theme = 'sphinx_rtd_theme'
+html_theme = "sphinx_rtd_theme"
 #html_static_path = ['_static']

doc/contents/auxiliary.rst

@@ -1,51 +1,27 @@
-Auxiliary module
+Auxiliary Module
 ################################
 
-The :index:`auxiliary` module contains functionalities for preparing input and processing outputs of various simulations.
+The :index:`auxiliary` module contains corollary functions that support the capabilities of the 
+platform's core modules (e.g., the source, ground-motion, and site-response modules).
+This module, therefore, acts as a bridge between raw data and the functions available in the simulation platform 
+by supporting I/O tools, statistical analysis, visualisation, and data management.
 
-In particular, it provides:
+Currently, the Auxiliary Module includes functions underpinning the Seismic Source Module 
+and its associated case study. 
 
-- Tools for preparing the input to MCQsim and post-processing the output.
+However, as the project will progress to ground motion and site modules, new functionalities 
+will be integrated into this framework. Consequently, this task will remain active throughout 
+the project, enabling continuous updates and refinements in response to the platform's evolving 
+requirements.
 
-Pre-simulation
-*********************************************
+To ensure a structured development process, the module is, for time being, subdivided into 
+three primary sub-sections: catalogue processing, statistical tools - plotting, and spatial 
+distributions.
 
-The pre-simulation tool focuses on preparing and managing input information.
-Its core functionalities include:
+Tutorial Contents
+-----------------
 
-- **Fault information management**: 
-  Import and modify fault segment data stored in GeoJSON format, including geometrical and attribute handling;
-
-- **Geometry validation**: 
-  Check and validate the geometric consistency of fault segments to ensure accurate meshing and simulation;
-
-- **Triangular meshing**:
-  Generate triangular meshes based on the fault geometry, enabling detailed structural representation;
-
-- **STL file creation**:
-  Convert the meshed fault segments into STL (Stereolithography or Standard Triangle Language) file format, 
-  suitable for 3D visualization and numerical simulations;
-
-
-Post simulation
-*********************************************
-
-The post-simulation tool focuses on processing output results.
-Its core functionalities include:
-
-- **Catalog processing**: 
-  Load catalogue as a `.mat` file and save it as a `.csv` file;
-
-- **Statistical evaluation**: 
-  Compute statistics for magnitude, rupture area, mean slip, and mean stress drop;
-
-- **3D spatial visualization**: 
-  Visualize spatial distribution of events;
-
-- **Magnitude-frequency distribution (MFD)**: 
-  Generate MFDs of the simulated earthquake catalogue;
-
-
-PSHA
-*********************************************
+.. toctree::
+   :maxdepth: 1
 
+   ses_processing

doc/contents/case.rst

@@ -1,9 +1,12 @@
-Ground motion module
+Ground Motion Module
 ################################
 
 The *ground motion module* will contain functionalities for computing ground motion parameters 
 using ground-motion models (GMMs) implemented into the OQ Engine. 
 
 
+In progress..
+
+
 
 

doc/contents/gmc.rst

@@ -0,0 +1,85 @@
+Installation
+################################
+
+This guide covers the necessary steps to set up your environment for the **Simulation Platform**. You will need to install Python dependencies and system-level tools like the Generic Mapping Tools (GMT).
+Also, the tutorials rely on the **OpenQuake Model Building Toolkit (oq-mbtk)** for seismic catalogue processing and statistical analysis. Before proceeding, you must have ``oq-mbtk`` installed.
+
+Here we demonstrate the installation of the QuakeT and its necessary dependencies, respectively. 
+
+Get the QuakeT Source Code
+==========================
+
+Open a terminal and move to the folder where you intend to install the tools;
+
+Clone the repository using the `web URL of QuakeT repository: <https://github.com/GEMScienceTools/quakeT.git>`_
+
+.. code-block:: bash
+
+    git clone https://github.com/GEMScienceTools/quakeT.git
+
+Go to the folder where you cloned the QuakeT repository and make it in “editable” mod running the following command:
+
+.. code-block:: bash
+
+    pip install -e .
+
+OpenQuake MBTK Setup
+========================
+Please follow the official installation instructions of **oq-mbtk** here:
+`OpenQuake MBTK Installation Guide. <https://gemsciencetools.github.io/oq-mbtk/contents/installation.html>`_
+
+Python Environment Setup
+========================
+
+It is highly recommended to use a virtual environment (conda or venv) to avoid dependency conflicts.
+
+.. code-block:: bash
+
+    # Create and activate a virtual environment (optional)
+    python -m venv quaket_env
+    source quaket_env/bin/activate  # On Windows: quaket_env\Scripts\activate
+
+    # Install Python libraries
+    pip install pandas geopandas shapely matplotlib ipython
+
+System Requirements
+===================
+
+The spatial distribution tutorials require **GMT** to be installed on your operating system.
+
+macOS
+-----
+
+The easiest way to install these tools on macOS is using `Homebrew <https://brew.sh/>`_:
+
+.. code-block:: bash
+
+    brew install gmt
+
+Windows
+-------
+
+1. **GMT:** Download and run the executable installer (.exe) from the `GMT Official Releases <https://www.generic-mapping-tools.org/download/>`_. During installation, ensure you check the box **"Add GMT to the system PATH"**.
+2. **Ghostscript:** (Required by GMT for PNG output) Download and install from the `Ghostscript site <https://ghostscript.com/releases/gsdnld.html>`_.
+
+Linux
+-------
+
+Use the package manager to install the required tools:
+
+.. code-block:: bash
+
+    sudo apt update
+    sudo apt install gmt gmt-dcw gmt-gshhg
+
+Verification
+============
+
+After installation, verify that the tools are correctly set up by running these commands in your terminal or command prompt:
+
+.. code-block:: bash
+
+    gmt --version
+
+.. note::
+   If you receive a "command not found" error, you may need to restart your terminal or manually add the installation folders to your system's Environment Variables (PATH).

doc/contents/installation.rst

@@ -0,0 +1,3 @@
+{
+    "path": "../../openquake/quaket/auxiliary/ses_processing.ipynb"
+}

doc/contents/ses_processing.nblink

@@ -1,7 +1,11 @@
-Site and site-effects module
+Site and Site-Effects Module
 ################################
 
 Within the *site and site-effects module*, functionalities will be developed for modelling the site response.
 
 
+In progress..
+
+
+
 

doc/contents/site.rst

@@ -1,7 +1,11 @@
-Seismic source module
+Seismic Source Module
 ################################
 
 The *seismic source module* will contain codes for evaluating models related to seismic sources.
 
 
+In progress..
+
+
+