Migrate RAVEN GIS utilities and fix the documentation

.cruft.json

@@ -23,4 +23,4 @@
         }
     },
     "directory": null
-}
+}

.gitignore

@@ -110,9 +110,3 @@ ENV/
 
 # Download and compile site for Raven and Ostrich binaries
 external_deps
-
-# Generated by Sphinx
-modules.rst
-ravenpy.models.rst
-ravenpy.rst
-ravenpy.utilities.rst

.pre-commit-config.yaml

@@ -0,0 +1,57 @@
+default_language_version:
+    python: python3
+
+repos:
+-   repo: https://github.com/asottile/pyupgrade
+    rev: v2.10.0
+    hooks:
+    -   id: pyupgrade
+        language_version: python3
+-   repo: https://github.com/kynan/nbstripout
+    rev: 0.3.9
+    hooks:
+    -   id: nbstripout
+        language_version: python3
+        files: ".ipynb"
+        args: ["--keep-output"]
+-   repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v3.4.0
+    hooks:
+    -   id: trailing-whitespace
+        language_version: python3
+        exclude: .rvc|.rvh|.rvi|.rvp|.rvt|.tpl|.txt
+    -   id: end-of-file-fixer
+        language_version: python3
+        exclude: .ipynb|.rvc|.rvh|.rvi|.rvp|.rvt|.tpl|.txt
+    -   id: check-yaml
+        language_version: python3
+    -   id: debug-statements
+        language_version: python3
+-   repo: https://github.com/ambv/black
+    rev: 20.8b1
+    hooks:
+    -   id: black
+        language_version: python3
+        args: ["--target-version", "py36"]
+-   repo: https://github.com/pycqa/flake8
+    rev: 3.8.4
+    hooks:
+    -   id: flake8
+        language_version: python3
+        args: ['--config=setup.cfg']
+-   repo: https://github.com/timothycrosley/isort
+    rev: 5.7.0
+    hooks:
+    -   id: isort
+        language_version: python3
+        args: ['--profile', 'black', '--filter-files']
+-   repo: https://github.com/pycqa/pydocstyle
+    rev: 5.1.1
+    hooks:
+    -   id: pydocstyle
+        language_version: python3
+        args: ['--convention=numpy', '--match="(?!test_).*\.py"']
+-   repo: meta
+    hooks:
+    -   id: check-hooks-apply
+    -   id: check-useless-excludes

LICENSE

@@ -19,4 +19,3 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
-

Makefile

@@ -64,8 +64,8 @@ coverage: ## check code coverage quickly with the default Python
 	$(BROWSER) htmlcov/index.html
 
 docs: ## generate Sphinx HTML documentation, including API docs
-	rm -f docs/ravenpy.rst
-	rm -f docs/modules.rst
+	# Warning: as the sphinx-apidoc is NOT being run on the RTD server the workaround we have
+	# is to commit the (currently 5) rst files it generates.
 	sphinx-apidoc -o docs/ ravenpy
 	$(MAKE) -C docs clean
 	$(MAKE) -C docs html

docs/Makefile

@@ -17,4 +17,4 @@ help:
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" -W $(SPHINXOPTS) $(O)

docs/conf.py

@@ -20,9 +20,9 @@
 import os
 import sys
 
-sys.path.insert(0, os.path.abspath('..'))
+sys.path.insert(0, os.path.abspath(".."))
 
-import ravenpy
+import ravenpy  # noqa
 
 # -- General configuration ---------------------------------------------
 
@@ -32,44 +32,57 @@
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc',
-              'sphinx.ext.autosummary',
-              'sphinx.ext.viewcode',
-              'numpydoc',
-              'nbsphinx',
-              'sphinx_click']
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.napoleon",
+    "nbsphinx",
+    "sphinx_click",
+]
+
+autosummary_generate = True
+nbsphinx_execute = "auto"
 
 # To avoid having to install these and burst memory limit on ReadTheDocs.
 autodoc_mock_imports = [
-    'affine',
-    'clisops',
-    'dataclasses',  # needed for python3.6
-    'fiona',
-    'gdal',
-    'osgeo',
-    'geopandas',
-    'lxml',
-    'owslib',
-    'pyproj',
-    'rasterio',
-    'rioxarray',
-    'shapely'
+    "affine",
+    "cftime",
+    "click",
+    "climpred",
+    "clisops",
+    "fiona",
+    "gdal",
+    "netCDF4",
+    "osgeo",
+    "geopandas",
+    "lxml",
+    "owslib",
+    "pandas",
+    "pyproj",
+    "rasterio",
+    "rioxarray",
+    "scipy",
+    "shapely",
+    "statsmodels",
+    "xarray",
+    "xclim",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
+templates_path = ["_templates"]
 
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 #
 # source_suffix = ['.rst', '.md']
-source_suffix = '.rst'
+source_suffix = ".rst"
 
 # The master toctree document.
-master_doc = 'index'
+master_doc = "index"
 
 # General information about the project.
-project = 'RavenPy'
+project = "RavenPy"
 copyright = "2020, David Huard"
 author = "David Huard"
 
@@ -92,26 +105,26 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This patterns also effect to html_static_path and html_extra_path
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
 # The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'sphinx'
+pygments_style = "sphinx"
 
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = False
 
 # Suppress "WARNING: unknown mimetype for ..." when building EPUB.
-suppress_warnings = ['epub.unknown_project_files']
+suppress_warnings = ["epub.unknown_project_files"]
 
 # Avoid "configuration.rst:4:duplicate label configuration, other instance in configuration.rst"
-autosectionlabel_prefix_document = True
+autosectionlabel_prefix_document = False
 
 # -- Options for HTML output -------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'sphinx_rtd_theme'
+html_theme = "sphinx_rtd_theme"
 
 # 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
@@ -122,28 +135,25 @@
 # 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,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+html_static_path = list()  # "_static"
 
 # -- Options for HTMLHelp output ---------------------------------------
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'ravenpydoc'
+htmlhelp_basename = "ravenpydoc"
 
 # -- Options for LaTeX output ------------------------------------------
 
 latex_elements = {
     # The paper size ('letterpaper' or 'a4paper').
     #
     # 'papersize': 'letterpaper',
-
     # The font size ('10pt', '11pt' or '12pt').
     #
     # 'pointsize': '10pt',
-
     # Additional stuff for the LaTeX preamble.
     #
     # 'preamble': '',
-
     # Latex figure (float) alignment
     #
     # 'figure_align': 'htbp',
@@ -153,31 +163,28 @@
 # (source start file, target name, title, author, documentclass
 # [howto, manual, or own class]).
 latex_documents = [
-    (master_doc, 'ravenpy.tex',
-     'RavenPy Documentation',
-     'David Huard', 'manual'),
+    (master_doc, "ravenpy.tex", "RavenPy Documentation", "David Huard", "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, 'ravenpy',
-     'RavenPy Documentation',
-     [author], 1)
-]
+man_pages = [(master_doc, "ravenpy", "RavenPy Documentation", [author], 1)]
 
 # -- Options for Texinfo output ----------------------------------------
 
 # Grouping the document tree into Texinfo files. List of tuples
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-    (master_doc, 'ravenpy',
-     'RavenPy Documentation',
-     author,
-     'ravenpy',
-     'One line description of project.',
-     'Miscellaneous'),
+    (
+        master_doc,
+        "ravenpy",
+        "RavenPy Documentation",
+        author,
+        "ravenpy",
+        "One line description of project.",
+        "Miscellaneous",
+    ),
 ]

docs/index.rst

@@ -18,17 +18,22 @@ RavenPy downloads and compiles the most recent version of the Raven, and offers
 
 .. toctree::
    :maxdepth: 1
-   :caption: Scripts
+   :caption: Utility Scripts
 
    scripts
 
-
 .. toctree::
    :maxdepth: 1
-   :caption: API
+   :caption: User API
 
    user_api
 
+.. toctree::
+   :maxdepth: 1
+   :caption: All Modules
+
+   modules
+
 
 Credits
 =======