docs: Finalized all docstrings and the api docs. Corrected the API docs layout by now expliciting the modules instead of relying too much in autosummary. The latter is only used to create summary tables in the APi landing page. Renamed case_f to case_g. Fixed link to matplotlib docs. Added catch for floatcsep logger, to detect if sphinx is being used and relay to the general logger instead of floatlogger

build: updated requirements and rev_reqs

Author: pabloitu

docs/conf.py

@@ -6,54 +6,62 @@
 import sys
 from sphinx_gallery.sorting import FileNameSortKey
 
-sys.path.insert(0, os.path.abspath('..'))
+sys.path.insert(0, os.path.abspath(".."))
+
+#  NOTE: To expose sphinx warnings, comment `setup_logger()` in floatcsep.commands.main
+
 
 # -- Project information -----------------------------------------------------
 
-project = 'floatCSEP'
-copyright = '2022, Pablo Iturrieta'
-author = 'Pablo Iturrieta'
-release = 'v0.1.0'
+project = "floatCSEP"
+copyright = "2022, Pablo Iturrieta"
+author = "Pablo Iturrieta"
+release = "v0.1.0"
 
 # -- General configuration ---------------------------------------------------
 
 extensions = [
-    'sphinx.ext.autodoc',
-    'sphinx.ext.todo',
-    'sphinx.ext.autosummary',
-    'sphinx.ext.coverage',
-    'sphinx.ext.mathjax',
-    'sphinx.ext.viewcode',
-    'sphinx.ext.napoleon',
-    'sphinx.ext.intersphinx',
-    # 'sphinx_gallery.gen_gallery',
-    # 'sphinx.ext.githubpages'
+    "sphinx.ext.autodoc",
+    "sphinx.ext.todo",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.coverage",
+    "sphinx.ext.mathjax",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.intersphinx",
 ]
 
-templates_path = ['_templates']
-source_suffix = '.rst'
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
-pygments_style = 'default'  # todo
-autodoc_typehints = 'none'
+# language = 'en'
+autosummary_generate = False
+autoclass_content = "both"
+suppress_warnings = [
+    "autosummary",
+    "autosummary.missing",
+]
+templates_path = ["_templates"]
+source_suffix = ".rst"
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+pygments_style = "default"
+autodoc_typehints = "description"
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3/", None),
-    "numpy": ("https://docs.scipy.org/doc/numpy/", None),
-    "pandas": ("http://pandas.pydata.org/pandas-docs/stable/", None),
-    "scipy": ('http://docs.scipy.org/doc/scipy/reference', None),
-    "matplotlib": ('http://matplotlib.sourceforge.net/', None),
-    'pycsep': ('https://docs.cseptesting.org/', None)
+    "numpy": ("https://numpy.org/doc/stable/", None),
+    "pandas": ("https://pandas.pydata.org/pandas-docs/stable/", None),
+    "scipy": ("https://docs.scipy.org/doc/scipy/", None),
+    "matplotlib": ("https://matplotlib.org/stable", None),
+    "pycsep": ("https://docs.cseptesting.org/", None),
 }
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
-html_theme = 'sphinx_rtd_theme'
-html_static_path = ['_static']
+html_theme = "sphinx_rtd_theme"
+html_static_path = ["_static"]
 html_theme_options = {
-    'display_version': True,
-    'prev_next_buttons_location': 'both',
-    'collapse_navigation': False,
-    'style_nav_header_background': '#343131ff',
-    'logo_only': True,
+    "display_version": True,
+    "prev_next_buttons_location": "both",
+    "collapse_navigation": False,
+    "style_nav_header_background": "#343131ff",
+    "logo_only": True,
 }
-html_logo = '_static/floatcsep_logo.svg'
+html_logo = "_static/floatcsep_logo.svg"
 todo_include_todos = False

docs/examples/case_f.rst renamed to docs/examples/case_g.rst

@@ -1,5 +1,5 @@
-A - Simple(st) Time-Dependent, Catalog-based Model
-==================================================
+G - Time-Dependent, Catalog-Based Model (from Source Code)
+==========================================================
 
 .. currentmodule:: floatcsep
 
@@ -8,7 +8,7 @@ A - Simple(st) Time-Dependent, Catalog-based Model
 
 .. admonition:: **TL; DR**
 
-    In a terminal, navigate to ``floatcsep/examples/case_f`` and type:
+    In a terminal, navigate to ``floatcsep/examples/case_g`` and type:
 
     .. code-block:: console
 
@@ -23,7 +23,7 @@ Artifacts
 This example shows how a time-dependent model should be set up for a time-dependent experiment
 ::
 
-    case_f
+    case_g
         └──  pymock
             ├── input
                 ├── args.txt  (model arguments)
@@ -49,7 +49,7 @@ The experiment's complexity increases from time-independent to dependent, since
 
     1. The input data is, at the least, a catalog filtered until the forecast beginning, which is automatically allocated by ``fecsep`` in the `{model}/input` prior to each model's run. It is stored inside the model in ``csep.ascii`` format for simplicity's sake (see :doc:`pycsep:concepts/catalogs`).
 
-    .. literalinclude:: ../../examples/case_f/catalog.csv
+    .. literalinclude:: ../../examples/case_g/catalog.csv
         :lines: 1-2
 
     2. The input arguments controls how the source code works. The minimum arguments to run a model (which should be modified dynamically during an experiment) are the forecast ``start_date`` and ``end_date``. The experiment will read `{model}/input/args.txt` and change the values of ``start_date = {datetime}`` and ``end_date = {datetime}`' before the model is run. Additional arguments can be set by convenience, such as ``catalog`` (the input catalog name), ``n_sims`` (number of synthetic catalogs) and random ``seed`` for reproducibility.
@@ -80,7 +80,7 @@ Time
 
     The configuration is identical to time-independent models, with the exception that now a ``horizon`` can be defined instead of ``intervals``, which is the forecast time-window length. The experiment's class should now be explicited as ``exp_class: td``
 
-    .. literalinclude:: ../../examples/case_f/config.yml
+    .. literalinclude:: ../../examples/case_g/config.yml
        :language: yaml
        :lines: 3-7
 
@@ -94,7 +94,7 @@ Models
 
     Additional arguments should be passed to time-independent models.
 
-    .. literalinclude:: ../../examples/case_f/models.yml
+    .. literalinclude:: ../../examples/case_g/models.yml
        :language: yaml
        :lines: 3-7
 
@@ -110,7 +110,7 @@ Tests
     With time-dependent models, now catalog evaluations found in :obj:`csep.core.catalog_evaluations` can be used.
 
 
-    .. literalinclude:: ../../examples/case_f/tests.yml
+    .. literalinclude:: ../../examples/case_g/tests.yml
        :language: yaml
 
     .. note::
@@ -120,7 +120,7 @@ Tests
 Running the experiment
 ----------------------
 
-    The experiment can be run by simply navigating to the ``examples/case_f`` folder in the terminal and typing.
+    The experiment can be run by simply navigating to the ``examples/case_g`` folder in the terminal and typing.
 
     .. code-block:: console
 

docs/index.rst

@@ -26,7 +26,7 @@ Preliminary documentation.
    examples/case_c.rst
    examples/case_d.rst
    examples/case_e.rst
-   examples/case_f.rst
+   examples/case_g.rst
 
 
 .. toctree::
@@ -46,7 +46,7 @@ Preliminary documentation.
    deployment/intro.rst
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 0
    :caption: Help & Reference
 
    reference/api_reference

docs/intro/concepts.rst

@@ -13,7 +13,7 @@ A Floating Testing Experiment encapsulates each experiment into its own runnable
 evaluations.
 
 ``floatCSEP`` goals
-----------------
+-------------------
 
 This is an application to deploy reproducible and prospective experiments of earthquake forecasting, namely a Floating Eperiment, that can operate independent of a particular testing server. With this application, researchers, institutions and users can