Use new theme for docs (#259)

* Use new theme

* Refactor index

* Update title

* Minor doc fixes

* Remove missing module

* Do not build pdf

* Reintroduce author

* Move interactive example to left sidebar

* More consistent spelling of pysteps

* Some cleanups in the docstrings

* Remove pages not used anymore

.github/workflows/test_pysteps.yml

@@ -1,4 +1,4 @@
-name: Test Pysteps
+name: Test pysteps
 
 env:
   MINIMAL_DEPENDENCIES: cython numpy jsmin jsonschema matplotlib netCDF4 opencv pillow pyproj scipy dask

.readthedocs.yml

@@ -7,7 +7,7 @@ sphinx:
   configuration: doc/source/conf.py
 
 formats:
-    - pdf
+    - htmlzip
 
 python:
   version: 3.8

CONTRIBUTING.rst

@@ -1,7 +1,7 @@
-Contributing to Pysteps
+Contributing to pysteps
 =======================
 
-Welcome! pySTEPS is a community-driven initiative for developing and
+Welcome! Pysteps is a community-driven initiative for developing and
 maintaining an easy to use, modular, free and open-source Python
 framework for short-term ensemble prediction systems.
 
@@ -108,7 +108,7 @@ root::
 
 The pre-commit hooks are scripts executed automatically in every commit to identify simple issues with the code.
 When an issue is identified (the pre-commit script exits with non-zero status), the hook aborts the commit and prints the error.
-Currently, Pysteps only tests that the code to be committed complies with black's format style.
+Currently, pysteps only tests that the code to be committed complies with black's format style.
 In case that the commit is aborted, you only need to run black in the entire source code.
 This can be done by running :code:`black .` or :code:`pre-commit run --all-files`.
 The latter is recommended since it indicates if the commit contained any formatting errors (that are automatically corrected).
@@ -310,7 +310,8 @@ Here is a summary of the most important rules:
 Here is an example of a docstring::
 
     def adjust_lag2_corrcoef1(gamma_1, gamma_2):
-        """A simple adjustment of lag-2 temporal autocorrelation coefficient to
+        """
+        A simple adjustment of lag-2 temporal autocorrelation coefficient to
         ensure that the resulting AR(2) process is stationary when the parameters
         are estimated from the Yule-Walker equations.
 
@@ -364,7 +365,7 @@ Testing your changes
 ~~~~~~~~~~~~~~~~~~~~
 
 Before committing changes or creating pull requests, check that all the tests in the pysteps suite pass.
-See the `Testing pySTEPS <https://pysteps.readthedocs.io/en/latest/developer_guide/test_pysteps.html#testing-pysteps>`__
+See the `Testing pysteps <https://pysteps.readthedocs.io/en/latest/developer_guide/test_pysteps.html#testing-pysteps>`__
 for detailed instruction to run the tests.
 
 Although it is not strictly needed, we suggest creating minimal tests for new contributions to ensure that it achieves
@@ -382,7 +383,7 @@ A quick way to get familiar with the pytest syntax and the testing procedures
 is checking the python scripts present in the pysteps test module.
 
 Core developer guidelines
-~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Working directly on the master branch is discouraged and is reserved only
 for small changes and updates that do not compromise the stability of the code.
@@ -415,8 +416,7 @@ Processing pull requests
 .. _`Squash and merge`: https://github.com/blog/2141-squash-your-commits
 
 To process the pull request, we follow similar rules to those used in the
-`mypy <https://github.com/python/mypy/blob/master/CONTRIBUTING.md#core-developer-guidelines>`_
-project:
+`mypy developer guidelines <https://github.com/python/mypy/blob/master/CONTRIBUTING.md#core-developer-guidelines>`_:
 
 * Always wait for tests to pass before merging PRs.
 * Always use "`Squash and merge`_"  to merge PRs.

PKG-INFO

@@ -7,11 +7,11 @@ License: LICENSE
 Description: =======
 pySteps
 =======
-The pySTEPS initiative is a community that develops and maintains an easy to
+The pysteps initiative is a community that develops and maintains an easy to
 use, modular, free and open-source python framework for short-term ensemble
 prediction systems.
 
 The focus is on probabilistic nowcasting of radar precipitation fields,
-but pySTEPS is designed to allow a wider range of uses.
+but pysteps is designed to allow a wider range of uses.
 
 Platform: UNKNOWN

README.rst

@@ -1,5 +1,4 @@
-=====================================================================
-pySTEPS - Python framework for short-term ensemble prediction systems
+pysteps - Python framework for short-term ensemble prediction systems
 =====================================================================
 
 .. start-badges
@@ -23,7 +22,7 @@ pySTEPS - Python framework for short-term ensemble prediction systems
     :target: https://pysteps.readthedocs.io/
 
 .. |test| image:: https://github.com/pySTEPS/pysteps/workflows/Test%20Pysteps/badge.svg
-    :alt: Test Pysteps
+    :alt: Test pysteps
     :target: https://github.com/pySTEPS/pysteps/actions?query=workflow%3A"Test+Pysteps"
 
 .. |black| image:: https://github.com/pySTEPS/pysteps/workflows/Check%20Black/badge.svg

ci/test_plugin_support.py

@@ -3,7 +3,7 @@
 """
 Script to test the plugin support.
 
-This script assumes that a package created with the default Pysteps plugin template
+This script assumes that a package created with the default pysteps plugin template
 (and using the default values) is installed.
 
 https://github.com/pySTEPS/cookiecutter-pysteps-plugin

doc/requirements.txt

@@ -1,7 +1,7 @@
 # Additional requeriments related to the documentation build only
 sphinx
 sphinxcontrib.bibtex
-sphinx_rtd_theme
+sphinx-book-theme
 sphinx_gallery
 scikit-image
 pandas

doc/source/conf.py

@@ -6,6 +6,7 @@
 import os
 import subprocess
 import sys
+from datetime import datetime
 
 import json
 from jsmin import jsmin
@@ -52,18 +53,16 @@
 
 # General information about the project.
 project = "pysteps"
-copyright = "2020, PySteps developers"
-author = "PySteps developers"
+copyright = f"2018-{datetime.now():%Y}, pysteps developers"
+author = "pysteps developers"
 
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 def get_version():
-    """
-    Returns project version as string from 'git describe' command.
-    """
+    """Returns project version as string from 'git describe' command."""
 
     from subprocess import check_output
 
@@ -136,13 +135,32 @@ def set_root():
 #
 # html_theme = 'alabaster'
 # html_theme = 'classic'
-html_theme = "sphinx_rtd_theme"
+html_theme = "sphinx_book_theme"
+html_title = ""
+
+html_context = {
+    "github_user": "pySTEPS",
+    "github_repo": "pysteps",
+    "github_version": "master",
+    "doc_path": "doc",
+}
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
 #
-# html_theme_options = {}
+html_theme_options = {
+    "repository_url": "https://github.com/pySTEPS/pysteps",
+    "repository_branch": "master",
+    "path_to_docs": "doc/source",
+    "use_edit_page_button": True,
+    "use_repository_button": True,
+    "use_issues_button": True,
+}
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+html_logo = "../_static/pysteps_logo.png"
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
@@ -155,12 +173,12 @@ def set_root():
 #
 # This is required for the alabaster theme
 # refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars
-html_sidebars = {
-    "**": [
-        "relations.html",  # needs 'show_related': True theme option to display
-        "searchbox.html",
-    ]
-}
+# html_sidebars = {
+#     "**": [
+#         "relations.html",  # needs 'show_related': True theme option to display
+#         "searchbox.html",
+#     ]
+# }
 
 html_domain_indices = True
 
@@ -211,15 +229,14 @@ def set_root():
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    (master_doc, "pysteps.tex", "pysteps Reference", author, "manual"),
+    (master_doc, "pysteps.tex", "pysteps reference", author, "manual"),
 ]
 
 # -- Options for manual page output ---------------------------------------
 
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
-man_pages = [(master_doc, "pysteps", "pysteps Reference", [author], 1)]
-
+man_pages = [(master_doc, "pysteps", "pysteps reference", [author], 1)]
 # -- Options for Texinfo output -------------------------------------------
 
 # Grouping the document tree into Texinfo files. List of tuples
@@ -229,7 +246,7 @@ def set_root():
     (
         master_doc,
         "pysteps",
-        "pysteps Reference",
+        "pysteps reference",
         author,
         "pysteps",
         "One line description of project.",

doc/source/developer_guide/build_the_docs.rst

@@ -35,7 +35,7 @@ related to Sphinx that are specified in the doc/requirements.txt file:
 - sphinx
 - numpydoc
 - sphinxcontrib.bibtex
-- sphinx_rtd_theme
+- sphinx-book-theme
 - sphinx_gallery
 
 You can install these packages running `pip install -r doc/requirements.txt`.

doc/source/developer_guide/test_pysteps.rst

@@ -1,7 +1,7 @@
 .. _testing_pysteps:
 
 ===============
-Testing pySTEPS
+Testing pysteps
 ===============
 
 The pysteps distribution includes a small test suite for some of the
@@ -34,7 +34,7 @@ Manual testing
 Example data
 ------------
 
-The pySTEPS build-in tests require the pySTEPS example data installed.
+The build-in tests require the pysteps example data installed.
 See the installation instructions in the :ref:`example_data` section.
 
 Test an installed package

doc/source/developer_guide/update_conda_forge.rst

@@ -50,7 +50,7 @@ See the official `conda-forge documentation <http://conda-forge.org/docs/user/00
 Maintain pysteps conda-forge package
 ====================================
 
-Pysteps Core developers that are maintainers of the pysteps feedstock.
+Pysteps core developers that are maintainers of the pysteps feedstock.
 
 All pysteps developers listed as maintainers of the pysteps feedstock are given push access to the feedstock repository.
 This means that a maintainer can create branches in the main repository.

doc/source/index.rst

@@ -1,5 +1,4 @@
-====================================
-pySTEPS -- The nowcasting initiative
+pysteps -- The nowcasting initiative
 ====================================
 
 Pysteps is a community-driven initiative for developing and maintaining an easy
@@ -12,48 +11,37 @@ but pysteps is designed to allow a wider range of uses.
 Pysteps is actively developed on GitHub__, while a more thorough description
 of pysteps is available in the pysteps reference publication:
 
-Pulkkinen, S., D. Nerini, A. Perez Hortal, C. Velasco-Forero, U. Germann,
-A. Seed, and L. Foresti, 2019:  Pysteps:  an open-source Python library for
-probabilistic precipitation nowcasting (v1.0). *Geosci. Model Dev.*, **12 (10)**,
-4185–4219, doi:10.5194/gmd-12-4185-2019. [source__]
+.. note::
+   Pulkkinen, S., D. Nerini, A. Perez Hortal, C. Velasco-Forero, U. Germann,
+   A. Seed, and L. Foresti, 2019:  Pysteps:  an open-source Python library for
+   probabilistic precipitation nowcasting (v1.0). *Geosci. Model Dev.*, **12 (10)**,
+   4185–4219, doi:`10.5194/gmd-12-4185-2019 <https://doi.org/10.5194/gmd-12-4185-2019>`_.
 
 __ https://github.com/pySTEPS/pysteps
-__ https://doi.org/10.5194/gmd-12-4185-2019
-
-.. note:: Use pysteps to run your first extrapolation nowcast in Google Colab with `this interactive notebook`__.
-__ https://colab.research.google.com/github/pySTEPS/pysteps/blob/master/examples/my_first_nowcast.ipynb
-
-Documentation
-=============
-
-The documentation is separated in three big branches, intended for different
-audiences.
-
-:ref:`user-guide`
-~~~~~~~~~~~~~~~~~
-
-This section is intended for new pysteps users. It provides an introductory
-overview to the pysteps package, explains how to install it and make use of the
-most important features.
-
-:ref:`pysteps-reference`
-~~~~~~~~~~~~~~~~~~~~~~~~
-
-Comprehensive description of all the modules and functions available in pysteps.
-
-:ref:`contributors-guides`
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Resources and guidelines for pysteps developers and contributors.
-
-
-Contents
-========
 
 .. toctree::
-    :maxdepth: 1
+   :maxdepth: 1
+   :hidden:
+   :caption: For users
+
+   Installation <user_guide/install_pysteps>
+   Gallery <../auto_examples/index>
+   My first nowcast (Colab Notebook) <https://colab.research.google.com/github/pySTEPS/pysteps/blob/master/examples/my_first_nowcast.ipynb>
+   API Reference <pysteps_reference/index>
+   Example data <user_guide/example_data>
+   Configuration file (pystepsrc) <user_guide/set_pystepsrc>
+   Machine learning applications <user_guide/machine_learning_pysteps>
+   Bibliography <zz_bibliography>
 
-    user_guide/index
-    pysteps_reference/index
-    developer_guide/index
-    zz_bibliography
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+   :caption: For developers
+
+    Contributing Guide <developer_guide/contributors_guidelines>
+    Importer plugins <developer_guide/importer_plugins>
+    Testing <developer_guide/test_pysteps>
+    Building the docs <developer_guide/build_the_docs>
+    Packaging <developer_guide/pypi>
+    Publishing to conda-forge <developer_guide/update_conda_forge>
+    GitHub repository <https://github.com/pySTEPS/pysteps>

doc/source/pysteps_reference/index.rst

@@ -1,18 +1,17 @@
 .. _pysteps-reference:
 
-=================
-pySTEPS reference
-=================
+API Reference
+=============
 
 :Release: |version|
 :Date: |today|
 
 This page gives an comprehensive description of all the modules and functions
-available in pySTEPS.
+available in pysteps.
 
 .. toctree::
     :maxdepth: 2
-    :caption: Pysteps modules
+    :caption: API Reference
 
     pysteps
     cascade