Skip to content

Commit 1d911f2

Browse files
pabloitupabloitu
authored
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).
1 parent a696fb4 commit 1d911f2

File tree

114 files changed

+3014
-728
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

114 files changed

+3014
-728
lines changed

Diff for: ‎.github/workflows/build-sphinx.yml

+1-1
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@ jobs:
2525
2626
- name: Install floatCSEP
2727
run: |
28-
pip install sphinx sphinx-autoapi sphinx-gallery sphinx-rtd-theme
28+
pip install -r requirements_dev.txt
2929
pip install --no-deps -e .
3030
python -c "import floatcsep; print('Version: ', floatcsep.__version__)"
3131

Diff for: ‎.github/workflows/release-tutorials.yml

+24
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
name: Release Tutorials
2+
3+
on:
4+
release:
5+
types: [ published ]
6+
7+
jobs:
8+
upload-tutorials:
9+
runs-on: ubuntu-latest
10+
11+
steps:
12+
- name: Check out the code
13+
uses: actions/checkout@v3
14+
15+
- name: Zip the tutorials folder
16+
run: |
17+
zip -r tutorials.zip tutorials/
18+
19+
- name: Upload the tutorials.zip to the release
20+
uses: softprops/action-gh-release@v1
21+
with:
22+
files: tutorials.zip
23+
env:
24+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Diff for: ‎MANIFEST.in

+1-1
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@ include README.md
22
include CODE_OF_CONDUCT.md
33
include requirements.txt
44
include requirements_dev.txt
5+
include environment.yml
56
include setup.py
67
include setup.cfg
78
include pyproject.toml
@@ -14,7 +15,6 @@ graft tests
1415
graft docs
1516
prune docs/_build
1617
prune docs/referenced/generated
17-
prune docs/tutorials/
1818

1919
global-exclude .git*
2020
global-exclude *.pyc

Diff for: ‎README.md

+33-16
Original file line numberDiff line numberDiff line change
@@ -20,9 +20,11 @@
2020
<a href="https://doi.org/10.5281/zenodo.7953816"><img src="https://zenodo.org/badge/DOI/10.5281/zenodo.7953816.svg" alt="DOI"></a>
2121
</p>
2222

23-
* Set up a testing **experiment** for your earthquake forecasts using authoritative data sources and benchmarks.
23+
* Set up a testing **experiment** for your earthquake forecasts using authoritative data sources
24+
and benchmarks.
2425
* **Encapsulate** the complete experiment's definition and rules in a couple of lines.
25-
* **Reproduce**, **reuse**, and **share** forecasting experiments from you, other researchers and institutions.
26+
* **Reproduce**, **reuse**, and **share** forecasting experiments from you, other researchers
27+
and institutions.
2628

2729
# Table of Contents
2830

@@ -34,12 +36,14 @@
3436
* [Contributing](#contributing)
3537
* [License](#license)
3638

37-
3839
# Installing floatCSEP
3940

40-
The core of `floatCSEP` is built around the `pyCSEP` package (https://github.com/sceccode/pycsep), which itself contains the core dependencies.
41+
The core of `floatCSEP` is built around the `pyCSEP`
42+
package (https://github.com/sceccode/pycsep), which itself contains the core dependencies.
4143

42-
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`
44+
The simplest way to install `floatCSEP`, is by creating a `conda`
45+
environment (https://conda.io - checkout Anaconda or Miniconda) and install `pyCSEP`
46+
from `conda-forge`
4347

4448
```
4549
conda env create -n $NAME
@@ -48,21 +52,29 @@ conda install -c conda-forge pycsep
4852
```
4953

5054
Clone and install the floatCSEP source code using `pip`
55+
5156
```
5257
git clone https://github.com/cseptesting/floatcsep
5358
cd floatcsep
5459
pip install .
5560
```
5661

57-
Please read the [Installation](https://floatcsep.readthedocs.io/en/latest/intro/installation.html) documentation for detailed instructions and additional installation methods.
62+
Please read
63+
the [Installation](https://floatcsep.readthedocs.io/en/latest/intro/installation.html)
64+
documentation for detailed instructions and additional installation methods.
5865

5966
# Run an Experiment
6067

61-
Using the command terminal, navigate to an example experiment in `floatcsep/examples/` and type
68+
Using the command terminal, navigate to an example experiment in ``floatcsep/tutorials/`` and
69+
type
70+
6271
```
6372
floatcsep run config.yml
6473
```
65-
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**!
74+
75+
A runtime directory will be created in a `results` folder. The experiment results can be
76+
visualized in `results/report.md`. **Check out the experiment, models and tests definition in
77+
the tutorials**!
6678

6779
# Important Links
6880

@@ -71,30 +83,35 @@ A runtime directory will be created in a `results` folder. The experiment result
7183
* `pyCSEP` [Github](https://github.com/sceccode/pycsep)
7284
* `pyCSEP` [Documentation](https://docs.cseptesting.org/)
7385

74-
7586
# Roadmap and Known Issues
7687

77-
* Add report customization
7888
* Create tool to check a TD model's interface with ``floatcsep``
7989
* Define a dependency strategy to ensure experiments' reproducibility.
8090
* Implement spatial database and HDF5 experiment storage feature
81-
* Set up task paralellization
82-
91+
* Set up task parallelization
92+
* Document the process of an experiment deployment
8393

8494
# Contributing
8595

86-
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
96+
We encourage all types of contributions, from reporting bugs, suggesting enhancements, adding
97+
new features and more. Please refer to
98+
the [Contribution Guidelines](https://github.com/cseptesting/floatcsep/blob/main/CONTRIBUTING.md)
99+
and the [Code of Conduct](https://github.com/cseptesting/floatcsep/blob/main/CODE_OF_CONDUCT.md)
100+
for more information
87101

88102
# License
89103

90-
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.
104+
The `floatCSEP` (as well as `pyCSEP`) software is distributed under the BSD 3-Clause open-source
105+
license. Please see
106+
the [license file](https://github.com/cseptesting/floatcsep/blob/main/LICENSE) for more
107+
information.
91108

92109
## Support
93110

94111
<div style="max-width: 100px; margin: auto;">
95112

96-
| <img src="https://i.postimg.cc/tC1LdjYf/scec.png" width="150"/> | <img src="https://i.postimg.cc/2S7ThcFM/eu-flag.jpg" width="150"/> |
97-
|:---|:---|
113+
| <img src="https://i.postimg.cc/tC1LdjYf/scec.png" width="150"/> | <img src="https://i.postimg.cc/2S7ThcFM/eu-flag.jpg" width="150"/> |
114+
|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
98115
| <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> |
99116

100117
</div>

Diff for: ‎docs/_static/custom.js

+31
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
/**
2+
* custom.js
3+
*
4+
* This script contains custom JavaScript modifications for the Sphinx documentation.
5+
* It can be expanded to include additional customizations related to behavior,
6+
* style, and functionality of the generated documentation.
7+
*
8+
*
9+
* Usage:
10+
* - Place this script in the _static directory of your Sphinx project.
11+
* - Include it in the html_js_files configuration in conf.py to load it automatically.
12+
* - Expand this file with other JavaScript customizations as needed.
13+
*
14+
* Author: Pablo Iturrieta
15+
* Date: 28.09.2024
16+
*/
17+
18+
document.addEventListener("DOMContentLoaded", function () {
19+
// - Ensures that all external links open in a new tab by adding the target="_blank"
20+
// attribute to all links with the 'external' class (automatically applied by Sphinx).
21+
// - Adds rel="noopener noreferrer" for security purposes, ensuring the new page
22+
// does not have access to the originating window context (prevents security risks).
23+
// Select all external links in the documentation
24+
const links = document.querySelectorAll('a.external');
25+
26+
// Loop through all the links and set them to open in a new tab
27+
links.forEach(function (link) {
28+
link.setAttribute('target', '_blank');
29+
link.setAttribute('rel', 'noopener noreferrer');
30+
});
31+
});

Diff for: ‎docs/_static/experiment_classes.png

286 KB
Loading

Diff for: ‎docs/_static/float_scheme.png

205 KB
Loading

Diff for: ‎docs/conf.py

+58-5
Original file line numberDiff line numberDiff line change
@@ -14,9 +14,9 @@
1414
# -- Project information -----------------------------------------------------
1515

1616
project = "floatCSEP"
17-
copyright = "2022, Pablo Iturrieta"
17+
copyright = "2024, Pablo Iturrieta"
1818
author = "Pablo Iturrieta"
19-
release = "v0.1.0"
19+
release = "v0.2.0"
2020

2121
# -- General configuration ---------------------------------------------------
2222

@@ -25,13 +25,20 @@
2525
"sphinx.ext.todo",
2626
"sphinx.ext.autosummary",
2727
"sphinx.ext.coverage",
28+
'sphinx_toolbox.github',
29+
'sphinx_toolbox.sidebar_links',
2830
"sphinx.ext.mathjax",
2931
"sphinx.ext.viewcode",
3032
"sphinx.ext.napoleon",
3133
"sphinx.ext.intersphinx",
34+
"sphinx_copybutton",
35+
"sphinx_design",
3236
]
3337

34-
# language = 'en'
38+
github_username = 'cseptesting'
39+
github_repository = 'floatcsep'
40+
41+
language = 'en'
3542
autosummary_generate = False
3643
autoclass_content = "both"
3744
suppress_warnings = [
@@ -51,6 +58,10 @@
5158
"matplotlib": ("https://matplotlib.org/stable", None),
5259
"pycsep": ("https://docs.cseptesting.org/", None),
5360
}
61+
todo_include_todos = False
62+
copybutton_prompt_text = "$ " # Text to ignore when copying (for shell commands)
63+
copybutton_only_copy_prompt_lines = False
64+
5465
# -- Options for HTML output -------------------------------------------------
5566
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
5667

@@ -59,9 +70,51 @@
5970
html_theme_options = {
6071
"display_version": True,
6172
"prev_next_buttons_location": "both",
62-
"collapse_navigation": False,
73+
"sticky_navigation": True,
74+
"collapse_navigation": True,
6375
"style_nav_header_background": "#343131ff",
6476
"logo_only": True,
6577
}
6678
html_logo = "_static/floatcsep_logo.svg"
67-
todo_include_todos = False
79+
html_js_files = [
80+
"custom.js",
81+
]
82+
83+
html_context = {
84+
"github_links": [
85+
(
86+
'Getting help',
87+
"https://github.com/cseptesting/floatcsep/issues"
88+
),
89+
(
90+
'Contributing',
91+
"https://github.com/cseptesting/floatcsep/blob/master/CONTRIBUTING.md"
92+
),
93+
(
94+
'Code of Conduct',
95+
"https://github.com/cseptesting/floatcsep/blob/master/CODE_OF_CONDUCT.md"
96+
),
97+
(
98+
'License',
99+
"https://github.com/cseptesting/floatcsep/blob/master/LICENSE"
100+
),
101+
(
102+
'Source Code',
103+
"https://github.com/cseptesting/floatcsep"
104+
),
105+
],
106+
}
107+
extlinks = {
108+
'github_contrib': ('https://github.com/cseptesting/floatcsep/main/blob/%s', ''),
109+
}
110+
rst_epilog = """
111+
.. raw:: html
112+
113+
<hr />
114+
<div style="text-align: center;">
115+
<a href="https://github.com/cseptesting/floatcsep">GitHub</a> |
116+
<a href="https://cseptesting.org">CSEP Website</a> |
117+
<a href="https://github.com/sceccode/pycsep">pyCSEP</a> |
118+
<a href="https://floatcsep.readthedocs.io/_/downloads/en/latest/pdf/">Download PDF</a>
119+
</div>
120+
"""

Diff for: ‎docs/deployment/intro.rst

-4
This file was deleted.

0 commit comments

Comments
 (0)