Merge pull request #105 from bird-house/refresh-cookiecutter-more-rob…

…ust-doc-build

Refresh cookiecutter for more robust doc build.

This PR applies the cookiecutter PR bird-house/cookiecutter-birdhouse#96 to ensure no silent ReadTheDocs build failure and for Travis-CI to also catch ReadTheDocs build failure before PR is merged.

Successful RtD generation: https://emu.readthedocs.io/en/test-rtd-build/ and matching RtD build logs: https://readthedocs.org/api/v2/build/11555381.txt

Changes:

* Turn RtD warnings to build failure so they do not fail silently.

* Change Travis-CI build config to also build Epub and Latex doc format to catch RtD failure on Travis-CI before PR is merged.

* Various changes to remove all warnings in doc build since warnings will now fail the doc build.

  * For doc build only, to work-around warnings, use a new PYWPS release to support RST anonymous links, currently installing PYWPS from source (with commit hash locked so it is reproducible) since no release yet (PR geopython/pywps#542)

  * Anaconda build badge do not exist anymore so it had to be removed.

Unrelated changes part of this PR (sorry !):

* Other cookiecutter changes that are unapplied previously are also part of this PR.  You might want to look at each commit to avoid the noises.

.cruft.json

@@ -1,6 +1,6 @@
 {
     "template": "https://github.com/bird-house/cookiecutter-birdhouse.git",
-    "commit": "73eee18ca4a16763335d18ed9512cc617fbcc777",
+    "commit": "7ec7b8b69bbb900d6a300854af0e2a7357b83cdf",
     "skip": [
         "emu/processes/wps_say_hello.py",
         "tests/test_wps_hello.py",

.readthedocs.yml

@@ -8,6 +8,9 @@ version: 2
 # Build documentation in the docs/ directory with Sphinx
 sphinx:
   configuration: docs/source/conf.py
+  # fail_on_warning might generate hard to fix error, in this case it can be
+  # disabled but this also means those errors will fail silently, choose wisely.
+  fail_on_warning: true
 
 # Build documentation with MkDocs
 #mkdocs:

.travis.yml

@@ -5,6 +5,7 @@ os:
 python:
   - "3.6"
   - "3.7"
+  - "3.8"
 #  - osx
 sudo: false
 before_install:
@@ -37,4 +38,6 @@ script:
   # No notebooks in emu yet.
   #- make test-notebooks
   - flake8
-  - make docs
+  - make docs  # default html
+  - make SPHINXOPTS='-b epub' docs  # to match RtD
+  - make SPHINXOPTS='-b latex' docs  # to match RtD

Dockerfile

@@ -16,11 +16,11 @@ COPY . /opt/wps
 
 WORKDIR /opt/wps
 
-# Create conda environment
-RUN conda env create -n wps -f environment.yml
+# Create conda environment with PyWPS
+RUN ["conda", "env", "create", "-n", "wps", "-f", "environment.yml"]
 
 # Install WPS
-RUN ["/bin/bash", "-c", "source activate wps && python setup.py develop"]
+RUN ["/bin/bash", "-c", "source activate wps && pip install -e ."]
 
 # Start WPS service on port 5000 on 0.0.0.0
 EXPOSE 5000

Makefile

@@ -72,6 +72,7 @@ install:
 develop:
 	@echo "Installing development requirements for tests and docs ..."
 	@-bash -c 'pip install -e ".[dev]"'
+	@-bash -c 'pip install git+https://github.com/Ouranosinc/pywps@2a55b6e95f51c648dc94bf3c89db7370b56c1c9c#egg=pywps --upgrade'
 
 .PHONY: start
 start:
@@ -163,7 +164,7 @@ refresh-notebooks:
 .PHONY: docs
 docs:
 	@echo "Generating docs with Sphinx ..."
-	@-bash -c '$(MAKE) -C $@ clean html'
+	@bash -c '$(MAKE) -C $@ clean html'
 	@echo "Open your browser to: file:/$(APP_ROOT)/docs/build/html/index.html"
 	## do not execute xdg-open automatically since it hangs travis and job does not complete
 	@echo "xdg-open $(APP_ROOT)/docs/build/html/index.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/source/conf.py

@@ -35,20 +35,35 @@
 
 # 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.viewcode',
-              'sphinx.ext.napoleon',
-              'sphinx.ext.todo',
-              'pywps.ext_autodoc',
-              ]
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.mathjax",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.todo",
+    "pywps.ext_autodoc",
+    "sphinx.ext.autosectionlabel",
+    "sphinx.ext.imgconverter",
+    "nbsphinx",
+    "IPython.sphinxext.ipython_console_highlighting",
+]
 
 # To avoid having to install these and burst memory limit on ReadTheDocs.
+# List of all tested working mock imports from all birds so new birds can
+# inherit without having to test which work which do not.
 autodoc_mock_imports = ["numpy", "xarray", "fiona", "rasterio", "shapely",
                         "osgeo", "geopandas", "pandas", "statsmodels",
                         "affine", "rasterstats", "spotpy", "matplotlib",
                         "scipy", "unidecode", "gdal", "sentry_sdk", "dask",
                         "numba", "parse", "siphon", "sklearn", "cftime",
-                        "netCDF4"]
+                        "netCDF4", "bottleneck", "ocgis", "geotiff", "geos",
+                        "hdf4", "hdf5", "zlib", "pyproj", "proj", "cartopy",
+                        "scikit-learn", "cairo"]
+
+# Monkeypatch constant because the following are mock imports.
+# Only works if numpy is actually installed and at the same time being mocked.
+#import numpy
+#numpy.pi = 3.1416
 
 # We are using mock imports in readthedocs, so probably safer to not run the notebooks
 nbsphinx_execute = 'never'
@@ -75,7 +90,7 @@
 # the built documents.
 #
 # The short X.Y version.
-version = ""
+version = "0.11.1"
 # The full version, including alpha/beta/rc tags.
 release = "0.11.1"
 
@@ -97,6 +112,12 @@
 # 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']
+
+# Avoid "configuration.rst:4:duplicate label configuration, other instance in configuration.rst"
+autosectionlabel_prefix_document = True
+
 
 # -- Options for HTML output -------------------------------------------
 

docs/source/installation.rst

@@ -14,10 +14,6 @@ Install from Conda
    :target: http://anaconda.org/birdhouse/emu
    :alt: Ananconda Install
 
-.. image:: http://anaconda.org/birdhouse/emu/badges/build.svg
-   :target: http://anaconda.org/birdhouse/emu
-   :alt: Anaconda Build
-
 .. image:: http://anaconda.org/birdhouse/emu/badges/version.svg
    :target: http://anaconda.org/birdhouse/emu
    :alt: Anaconda Version

emu/processes/wps_bbox.py

@@ -1,4 +1,5 @@
 from pywps.app.Common import Metadata
+from pywps.ext_autodoc import MetadataUrl
 
 __author__ = 'Jachym'
 
@@ -30,7 +31,9 @@ def __init__(self):
             abstract='Give bounding box, return the same',
             metadata=[
                 Metadata('Birdhouse', 'http://bird-house.github.io/'),
-                Metadata('User Guide', 'http://emu.readthedocs.io/en/latest/')],
+                MetadataUrl('User Guide',
+                            'http://emu.readthedocs.io/en/latest/',
+                            anonymous=True)],
             inputs=inputs,
             outputs=outputs,
             store_supported=True,

emu/processes/wps_binaryoperator.py

@@ -1,5 +1,6 @@
 from pywps import Process, LiteralInput, LiteralOutput
 from pywps.app.Common import Metadata
+from pywps.ext_autodoc import MetadataUrl
 
 import logging
 logger = logging.getLogger("PYWPS")
@@ -30,7 +31,9 @@ def __init__(self):
                      'This example process is taken from Climate4Impact.',
             metadata=[
                 Metadata('Birdhouse', 'http://bird-house.github.io/'),
-                Metadata('User Guide', 'http://emu.readthedocs.io/en/latest/'),
+                MetadataUrl('User Guide',
+                            'http://emu.readthedocs.io/en/latest/',
+                            anonymous=True),
                 Metadata('Climate4Impact', 'https://dev.climate4impact.eu')],
             version='1.0',
             inputs=inputs,

emu/processes/wps_chomsky.py

@@ -102,8 +102,7 @@
 
 class Chomsky(Process):
     """
-    Notes
-    -----
+    Notes:
 
     Generates a random chomsky text:
     http://code.activestate.com/recipes/440546-chomsky-random-text-generator/

emu/processes/wps_dry_run.py

@@ -1,6 +1,6 @@
 from pywps import Process, LiteralInput, LiteralOutput
 from pywps.inout.literaltypes import AllowedValue
-from pywps.app.Common import Metadata
+from pywps.ext_autodoc import MetadataUrl
 from pywps.validator.mode import MODE
 
 from emu.exceptions import DryRunWarning, StorageLimitExceeded
@@ -32,7 +32,9 @@ def __init__(self):
             title='Simple Dry Run',
             abstract='A dummy download as simple dry-run example.',
             metadata=[
-                Metadata('User Guide', 'https://emu.readthedocs.io/en/latest/processes.html'),  # noqa
+                MetadataUrl('User Guide',
+                            'https://emu.readthedocs.io/en/latest/processes.html',
+                            anonymous=True),
             ],
             version='1.0',
             inputs=inputs,

emu/processes/wps_error.py

@@ -1,5 +1,6 @@
 from pywps import Process, LiteralInput
 from pywps.app.Common import Metadata
+from pywps.ext_autodoc import MetadataUrl
 from pywps.app.exceptions import ProcessError
 
 import logging
@@ -37,7 +38,10 @@ def __init__(self):
             metadata=[
                 Metadata('PyWPS', 'https://pywps.org/'),
                 Metadata('Birdhouse', 'http://bird-house.github.io/'),
-                Metadata('User Guide', 'http://emu.readthedocs.io/en/latest/')],
+                MetadataUrl('User Guide',
+                            'http://emu.readthedocs.io/en/latest/',
+                            anonymous=True),
+            ],
             version='1.0',
             inputs=inputs,
             # outputs=outputs,

emu/processes/wps_esgf.py

@@ -3,6 +3,7 @@
 from pywps import ComplexInput
 from pywps import Format
 from pywps.app.Common import Metadata
+from pywps.ext_autodoc import MetadataUrl
 
 import logging
 LOGGER = logging.getLogger("PYWPS")
@@ -38,7 +39,9 @@ def __init__(self):
             title='ESGF Demo',
             abstract='Shows how to use WPS metadata for processes using ESGF data.',
             metadata=[
-                Metadata('User Guide', 'https://emu.readthedocs.io/en/latest/processes.html'),  # noqa
+                MetadataUrl('User Guide',
+                            'https://emu.readthedocs.io/en/latest/processes.html',
+                            anonymous=True),
                 Metadata('ESGF Constraints',
                          role='https://www.earthsystemcog.org/spec/esgf_search/4.12.0/def/constraints',  # noqa
                          href='http://esgf-data.dkrz.de/esg-search/search?project=CMIP5&time_frequency=mon&variable=tas,tasmax,tasmin&experiment=historical'),  # noqa

emu/processes/wps_inout.py

@@ -9,6 +9,7 @@
 from pywps import Format, FORMATS
 from pywps.validator.mode import MODE
 from pywps.app.Common import Metadata
+from pywps.ext_autodoc import MetadataUrl
 
 
 import logging
@@ -67,8 +68,9 @@ def __init__(self):
             LiteralInput('int_range', 'Integer Range',
                          abstract='Choose number from range: 1-10 (step 1), 100-200 (step 10)',
                          metadata=[
-                            Metadata('PyWPS Docs', 'https://pywps.readthedocs.io/en/master/api.html#pywps.inout.literaltypes.AllowedValue'),  # noqa
-                            Metadata('AllowedValue Example', 'http://docs.opengeospatial.org/is/14-065/14-065.html#98'),  # noqa
+                             Metadata('AllowedValue PyWPS Docs',
+                                      'https://pywps.readthedocs.io/en/master/api.html#pywps.inout.literaltypes.AllowedValue'),  # noqa
+                             Metadata('AllowedValue Example', 'http://docs.opengeospatial.org/is/14-065/14-065.html#98'),  # noqa
                          ],
                          data_type='integer',
                          default='1',
@@ -80,15 +82,17 @@ def __init__(self):
             LiteralInput('any_value', 'Any Value',
                          abstract='Enter any value.',
                          metadata=[
-                            Metadata('PyWPS Docs', 'https://pywps.readthedocs.io/en/master/api.html#pywps.inout.literaltypes.AnyValue'),  # noqa
+                             Metadata('AnyValue PyWPS Docs',
+                                      'https://pywps.readthedocs.io/en/master/api.html#pywps.inout.literaltypes.AnyValue'),  # noqa
                          ],
                          allowed_values=AnyValue(),
                          default='any value',
                          mode=MODE.SIMPLE,),
             LiteralInput('ref_value', 'Referenced Value',
                          abstract='Choose a referenced value',
                          metadata=[
-                            Metadata('PyWPS Docs', 'https://pywps.readthedocs.io/en/master/_modules/pywps/inout/literaltypes.html'),  # noqa
+                             Metadata('PyWPS Docs',
+                                      'https://pywps.readthedocs.io/en/master/_modules/pywps/inout/literaltypes.html'),  # noqa
                          ],
                          data_type='string',
                          allowed_values=ValuesReference(
@@ -155,8 +159,10 @@ def __init__(self):
             # profile=['birdhouse'],
             metadata=[
                 Metadata('Birdhouse', 'http://bird-house.github.io/'),
-                Metadata('User Guide', 'http://emu.readthedocs.io/en/latest/',
-                         role='http://www.opengis.net/spec/wps/2.0/def/process/description/documentation')],
+                MetadataUrl('User Guide', 'http://emu.readthedocs.io/en/latest/',
+                            role='http://www.opengis.net/spec/wps/2.0/def/process/description/documentation',
+                            anonymous=True),
+            ],
             inputs=inputs,
             outputs=outputs,
             status_supported=True,

emu/processes/wps_multiple_outputs.py

@@ -2,7 +2,7 @@
 from pywps import Process, LiteralInput, ComplexOutput
 from pywps import FORMATS
 from pywps.inout.literaltypes import AllowedValue
-from pywps.app.Common import Metadata
+from pywps.ext_autodoc import MetadataUrl
 from pywps.inout.outputs import MetaLink, MetaLink4, MetaFile
 import json
 
@@ -36,7 +36,9 @@ def __init__(self):
             abstract='Produces multiple files and returns a document'
                      ' with references to these files.',
             metadata=[
-                Metadata('User Guide', 'https://emu.readthedocs.io/en/latest/processes.html'),  # noqa
+                MetadataUrl('User Guide',
+                            'https://emu.readthedocs.io/en/latest/processes.html',
+                            anonymous=True),
             ],
             version='1.1',
             inputs=inputs,

emu/processes/wps_nap.py

@@ -1,5 +1,6 @@
 from pywps import Process, LiteralInput, LiteralOutput
 from pywps.app.Common import Metadata
+from pywps.ext_autodoc import MetadataUrl
 
 
 class Nap(Process):
@@ -23,7 +24,10 @@ def __init__(self):
             profile='',
             metadata=[
                 Metadata('Birdhouse', 'http://bird-house.github.io/'),
-                Metadata('User Guide', 'http://emu.readthedocs.io/en/latest/')],
+                MetadataUrl('User Guide',
+                            'http://emu.readthedocs.io/en/latest/',
+                            anonymous=True),
+            ],
             inputs=inputs,
             outputs=outputs,
             store_supported=False,

emu/processes/wps_nc_to_dap.py

@@ -1,6 +1,6 @@
 from pywps import Process
 from pywps import ComplexInput, ComplexOutput, FORMATS
-from pywps.app.Common import Metadata
+from pywps.ext_autodoc import MetadataUrl
 from pywps import configuration
 import logging
 
@@ -33,7 +33,9 @@ def __init__(self):
             abstract="Return Data Access Protocol link to a netCDF or NcML file.",
             version="1",
             metadata=[
-                Metadata('User Guide', 'http://emu.readthedocs.io/en/latest/'),
+                MetadataUrl('User Guide',
+                            'http://emu.readthedocs.io/en/latest/',
+                            anonymous=True),
             ],
             inputs=inputs,
             outputs=outputs,

emu/processes/wps_ncmeta.py

@@ -4,7 +4,7 @@
 from pywps import ComplexInput, ComplexOutput, FORMATS, Format
 from pywps.inout.basic import SOURCE_TYPE
 from pywps.validator.mode import MODE
-from pywps.app.Common import Metadata
+from pywps.ext_autodoc import MetadataUrl
 
 from netCDF4 import Dataset
 
@@ -17,8 +17,7 @@
 
 class NCMeta(Process):
     """
-    Notes
-    -----
+    Notes:
 
     Returns metadata of a NetCDF file or OpenDAP resource.
     """
@@ -52,7 +51,9 @@ def __init__(self):
             abstract="Return metadata from a netCDF dataset, either on file or an OpenDAP service.",
             version='4',
             metadata=[
-                Metadata('User Guide', 'http://emu.readthedocs.io/en/latest/'),
+                MetadataUrl('User Guide',
+                            'http://emu.readthedocs.io/en/latest/',
+                            anonymous=True),
             ],
             inputs=inputs,
             outputs=outputs,