Merge pull request #34 from cseptesting/33-fix-api-reference-from-documentation

33 fix api reference from documentation

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