35 populate documentation with tutorials and configuration guides (#37)

* docs: finalized docstrings and API documentation

* docs: Added tutorial for case_f (time-dependent model with only forecast files).

* docs: Finalized example tutoriales for cases a-f.
fix: the configuration for plot_forecasts now accept `catalog: True` instead of a dictionary.

* docs: Finalized tutorials G and H. Reworked local TOC for all examples.

* docs: Updated frontpage

* docs: Updated docs front page with useful links.

* refac: Renamed examples folder to tutorials

* docs: Updated installation section, modified rtd options
gh: added a workflow to automatically add a tutorial zip file into any release files.

* docs: Re-wrote Concepts document.

* ft: time configuration can now be instantiated by explicit time windows
docs: completed Experiment Configuration section,

* docs: completed Model Configuration section,

* docs: started the evaluation config documentation. Wrote parameters for gridded-type forecasts.

* docs: Finished the evaluation config docs. Added .js to custom behavior of external links (now open in a new tab). Added sphinx-design for expandable tables.

* docs: added postprocess documentation. fixed link to experimental concepts.
ft: added simple method get_test to experiment class for users to quickly access an evaluation by its name.

* docs: added postprocess documentation. fixed link to experimental concepts.
ft: added simple method get_test to experiment class for users to quickly access an evaluation by its name

* docs: added executing experiment documentation

* build: added sphinx-design as dev requirement

* ci: now build-docs install the requirements_dev packages, instead of hardcoded sphinx packages in the config file.

* docs: added github context for html

* docs: added experiment classes figure. removed deployment guide, placed it in roadmap. fixed typos. Added sidebar links (and dependencies).

.github/workflows/build-sphinx.yml

@@ -25,7 +25,7 @@ jobs:
 
       - name: Install floatCSEP
         run: |
-          pip install sphinx sphinx-autoapi sphinx-gallery sphinx-rtd-theme
+          pip install -r requirements_dev.txt
           pip install --no-deps -e .
           python -c "import floatcsep; print('Version: ', floatcsep.__version__)"
 

.github/workflows/release-tutorials.yml

@@ -0,0 +1,24 @@
+name: Release Tutorials
+
+on:
+  release:
+    types: [ published ]
+
+jobs:
+  upload-tutorials:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out the code
+        uses: actions/checkout@v3
+
+      - name: Zip the tutorials folder
+        run: |
+          zip -r tutorials.zip tutorials/
+
+      - name: Upload the tutorials.zip to the release
+        uses: softprops/action-gh-release@v1
+        with:
+          files: tutorials.zip
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

MANIFEST.in

@@ -2,6 +2,7 @@ include README.md
 include CODE_OF_CONDUCT.md
 include requirements.txt
 include requirements_dev.txt
+include environment.yml
 include setup.py
 include setup.cfg
 include pyproject.toml
@@ -14,7 +15,6 @@ graft tests
 graft docs
 prune docs/_build
 prune docs/referenced/generated
-prune docs/tutorials/
 
 global-exclude .git*
 global-exclude *.pyc

README.md

@@ -20,9 +20,11 @@
 <a href="https://doi.org/10.5281/zenodo.7953816"><img src="https://zenodo.org/badge/DOI/10.5281/zenodo.7953816.svg" alt="DOI"></a>
 </p>
 
-* Set up a testing **experiment** for your earthquake forecasts using authoritative data sources and benchmarks.
+* Set up a testing **experiment** for your earthquake forecasts using authoritative data sources
+  and benchmarks.
 * **Encapsulate** the complete experiment's definition and rules in a couple of lines.
-* **Reproduce**, **reuse**, and **share** forecasting experiments from you, other researchers and institutions.
+* **Reproduce**, **reuse**, and **share** forecasting experiments from you, other researchers
+  and institutions.
 
 # Table of Contents
 
@@ -34,12 +36,14 @@
 * [Contributing](#contributing)
 * [License](#license)
 
-
 # Installing floatCSEP
 
-The core of `floatCSEP` is built around the `pyCSEP` package (https://github.com/sceccode/pycsep), which itself contains the core dependencies. 
+The core of `floatCSEP` is built around the `pyCSEP`
+package (https://github.com/sceccode/pycsep), which itself contains the core dependencies.
 
-The simplest way to install `floatCSEP`, is by creating a `conda` environment (https://conda.io - checkout Anaconda or Miniconda) and install `pyCSEP` from `conda-forge`
+The simplest way to install `floatCSEP`, is by creating a `conda`
+environment (https://conda.io - checkout Anaconda or Miniconda) and install `pyCSEP`
+from `conda-forge`
 
 ```
 conda env create -n $NAME
@@ -48,21 +52,29 @@ conda install -c conda-forge pycsep
 ```
 
 Clone and install the floatCSEP source code using `pip`
+
 ```
 git clone https://github.com/cseptesting/floatcsep
 cd floatcsep
 pip install .
 ```
 
-Please read the [Installation](https://floatcsep.readthedocs.io/en/latest/intro/installation.html) documentation for detailed instructions and additional installation methods.
+Please read
+the [Installation](https://floatcsep.readthedocs.io/en/latest/intro/installation.html)
+documentation for detailed instructions and additional installation methods.
 
 # Run an Experiment
 
-Using the command terminal, navigate to an example experiment in `floatcsep/examples/` and type
+Using the command terminal, navigate to an example experiment in ``floatcsep/tutorials/`` and
+type
+
 ```
 floatcsep run config.yml
 ```
-A runtime directory will be created in a `results` folder. The experiment results can be visualized in `results/report.md`. **Check out the experiment, models and tests definition in the examples**! 
+
+A runtime directory will be created in a `results` folder. The experiment results can be
+visualized in `results/report.md`. **Check out the experiment, models and tests definition in
+the tutorials**!
 
 # Important Links
 
@@ -71,30 +83,35 @@ A runtime directory will be created in a `results` folder. The experiment result
 * `pyCSEP` [Github](https://github.com/sceccode/pycsep)
 * `pyCSEP` [Documentation](https://docs.cseptesting.org/)
 
-
 # Roadmap and Known Issues
 
-* Add report customization
 * Create tool to check a TD model's interface with ``floatcsep``
 * Define a dependency strategy to ensure experiments' reproducibility.
 * Implement spatial database and HDF5 experiment storage feature
-* Set up task paralellization
-
+* Set up task parallelization
+* Document the process of an experiment deployment
 
 # Contributing
 
-We encourage all types of contributions, from reporting bugs, suggesting enhancements, adding new features and more. Please refer to the [Contribution Guidelines](https://github.com/cseptesting/floatcsep/blob/main/CONTRIBUTING.md) and the [Code of Conduct](https://github.com/cseptesting/floatcsep/blob/main/CODE_OF_CONDUCT.md) for more information
+We encourage all types of contributions, from reporting bugs, suggesting enhancements, adding
+new features and more. Please refer to
+the [Contribution Guidelines](https://github.com/cseptesting/floatcsep/blob/main/CONTRIBUTING.md)
+and the [Code of Conduct](https://github.com/cseptesting/floatcsep/blob/main/CODE_OF_CONDUCT.md)
+for more information
 
 # License
 
-The `floatCSEP` (as well as `pyCSEP`) software is distributed under the BSD 3-Clause open-source license. Please see the [license file](https://github.com/cseptesting/floatcsep/blob/main/LICENSE) for more information.
+The `floatCSEP` (as well as `pyCSEP`) software is distributed under the BSD 3-Clause open-source
+license. Please see
+the [license file](https://github.com/cseptesting/floatcsep/blob/main/LICENSE) for more
+information.
 
 ## Support
 
 <div style="max-width: 100px; margin: auto;">
 
-| <img src="https://i.postimg.cc/tC1LdjYf/scec.png" width="150"/> | <img src="https://i.postimg.cc/2S7ThcFM/eu-flag.jpg" width="150"/> |
-|:---|:---|
+| <img src="https://i.postimg.cc/tC1LdjYf/scec.png" width="150"/>                                                                                                                                                                                           | <img src="https://i.postimg.cc/2S7ThcFM/eu-flag.jpg" width="150"/>                                                                                                                                                                                                                                                               |
+|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | <div style="text-align: left;">This research was supported by the <a href="https://www.scec.org/">Statewide California Earthquake Center</a>. SCEC is funded by NSF Cooperative Agreement EAR-2225216 and USGS Cooperative Agreement G24AC00072-00.</div> | <div style="text-align: left;">The work in this repository has received funding from the European Union’s Horizon research and innovation programme under grant agreements No.s 101058518 and 821115 of the projects <a href="https://www.geo-inquire.eu/">GeoInquire</a> and <a href="https://www.rise-eu.org/">RISE</a>.</div> |
 
 </div>

docs/_static/custom.js

@@ -0,0 +1,31 @@
+/**
+ * custom.js
+ *
+ * This script contains custom JavaScript modifications for the Sphinx documentation.
+ * It can be expanded to include additional customizations related to behavior,
+ * style, and functionality of the generated documentation.
+ *
+ *
+ * Usage:
+ * - Place this script in the _static directory of your Sphinx project.
+ * - Include it in the html_js_files configuration in conf.py to load it automatically.
+ * - Expand this file with other JavaScript customizations as needed.
+ *
+ * Author: Pablo Iturrieta
+ * Date: 28.09.2024
+ */
+
+document.addEventListener("DOMContentLoaded", function () {
+//     - Ensures that all external links open in a new tab by adding the target="_blank"
+//       attribute to all links with the 'external' class (automatically applied by Sphinx).
+//     - Adds rel="noopener noreferrer" for security purposes, ensuring the new page
+//       does not have access to the originating window context (prevents security risks).
+    // Select all external links in the documentation
+    const links = document.querySelectorAll('a.external');
+
+    // Loop through all the links and set them to open in a new tab
+    links.forEach(function (link) {
+        link.setAttribute('target', '_blank');
+        link.setAttribute('rel', 'noopener noreferrer');
+    });
+});

docs/conf.py

@@ -14,9 +14,9 @@
 # -- Project information -----------------------------------------------------
 
 project = "floatCSEP"
-copyright = "2022, Pablo Iturrieta"
+copyright = "2024, Pablo Iturrieta"
 author = "Pablo Iturrieta"
-release = "v0.1.0"
+release = "v0.2.0"
 
 # -- General configuration ---------------------------------------------------
 
@@ -25,13 +25,20 @@
     "sphinx.ext.todo",
     "sphinx.ext.autosummary",
     "sphinx.ext.coverage",
+    'sphinx_toolbox.github',
+    'sphinx_toolbox.sidebar_links',
     "sphinx.ext.mathjax",
     "sphinx.ext.viewcode",
     "sphinx.ext.napoleon",
     "sphinx.ext.intersphinx",
+    "sphinx_copybutton",
+    "sphinx_design",
 ]
 
-# language = 'en'
+github_username = 'cseptesting'
+github_repository = 'floatcsep'
+
+language = 'en'
 autosummary_generate = False
 autoclass_content = "both"
 suppress_warnings = [
@@ -51,6 +58,10 @@
     "matplotlib": ("https://matplotlib.org/stable", None),
     "pycsep": ("https://docs.cseptesting.org/", None),
 }
+todo_include_todos = False
+copybutton_prompt_text = "$ "  # Text to ignore when copying (for shell commands)
+copybutton_only_copy_prompt_lines = False
+
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
@@ -59,9 +70,51 @@
 html_theme_options = {
     "display_version": True,
     "prev_next_buttons_location": "both",
-    "collapse_navigation": False,
+    "sticky_navigation": True,
+    "collapse_navigation": True,
     "style_nav_header_background": "#343131ff",
     "logo_only": True,
 }
 html_logo = "_static/floatcsep_logo.svg"
-todo_include_todos = False
+html_js_files = [
+    "custom.js",
+]
+
+html_context = {
+    "github_links": [
+        (
+            'Getting help',
+            "https://github.com/cseptesting/floatcsep/issues"
+        ),
+        (
+            'Contributing',
+            "https://github.com/cseptesting/floatcsep/blob/master/CONTRIBUTING.md"
+        ),
+        (
+            'Code of Conduct',
+            "https://github.com/cseptesting/floatcsep/blob/master/CODE_OF_CONDUCT.md"
+        ),
+        (
+            'License',
+            "https://github.com/cseptesting/floatcsep/blob/master/LICENSE"
+        ),
+        (
+            'Source Code',
+            "https://github.com/cseptesting/floatcsep"
+        ),
+    ],
+}
+extlinks = {
+    'github_contrib': ('https://github.com/cseptesting/floatcsep/main/blob/%s', ''),
+}
+rst_epilog = """
+.. raw:: html
+
+    <hr />
+    <div style="text-align: center;">
+        <a href="https://github.com/cseptesting/floatcsep">GitHub</a> |
+        <a href="https://cseptesting.org">CSEP Website</a> |
+        <a href="https://github.com/sceccode/pycsep">pyCSEP</a> |
+        <a href="https://floatcsep.readthedocs.io/_/downloads/en/latest/pdf/">Download PDF</a>
+    </div>
+"""