Merge pull request #167 from crim-ca/setup-docs

Setup docs

.codacy.yml

@@ -1,4 +1,4 @@
 ---
 exclude_paths:
   - 'tests/**'
-  - 'docs/conf.py'
+  - 'docs/source/conf.py'

CHANGES.rst

@@ -8,7 +8,8 @@ Changes
 
 Changes:
 --------
-- No change.
+- Generate Weaver OpenAPI specification for readthedocs publication.
+- Add some sections for documentation (`#61 <https://github.com/crim-ca/weaver/issues/61>`_).
 
 Fixes:
 ------

README.rst

@@ -97,7 +97,7 @@ For more details, see `Configuration`_ and `Documentation`_ sections.
 Links
 ----------------
 
-Docker image repositories: 
+Docker image repositories:
 
 - CRIM registry: `ogc/weaver <https://docker-registry.crim.ca/repositories/3463>`_
 - OGC processes: `ogc-public <https://docker-registry.crim.ca/namespaces/39>`_
@@ -140,28 +140,44 @@ For more configuration details, please refer to Documentation_.
 Documentation
 ----------------
 
-The REST API documentation is auto-generated and served under ``{WEAVER_URL}/api/`` using
-Swagger-UI with tag ``latest``.
+The REST API documentation is auto-generated and served under any running `Weaver` application on route
+``{WEAVER_URL}/api/``. This documentation will correspond to the version of the executed `Weaver` application.
+For the latest documentation, you can refer to the `OpenAPI Specification <rtd_oas>`_ served directly on `readthedocs`_.
 
-More ample details about installation, configuration and usage are provided on `readthedocs`_.
-These are generated from corresponding information provided in `docs`_.
+More ample details about installation, configuration and usage are also provided on `readthedocs`_.
+These are generated from corresponding information provided in `docs`_ source directory.
 
 .. _readthedocs: https://pavics-weaver.readthedocs.io
+.. _rtd_oas: https://pavics-weaver.readthedocs.io/en/latest/api.html
 .. _docs: ./docs
 
-----------------
-Extra Details
-----------------
+-------------------------
+Extra Details & Sponsors
+-------------------------
 
-The project is developed upon *OGC Testbed-14 – ESA Sponsored Threads – Exploitation Platform* findings and
+The project was initially developed upon *OGC Testbed-14 – ESA Sponsored Threads – Exploitation Platform* findings and
 following improvements. It is also advanced with sponsorship of *U.S. Department of Energy* to support common
-API of the *Earth System Grid Federation* (`ESGF`_).
+API of the *Earth System Grid Federation* (`ESGF`_). The findings are reported on the
+`OGC Testbed-14 <ogc-tb14>`_ thread, and more explicitly in the
+`ADES & EMS Results and Best Practices Engineering Report <ogc-tb14-platform-er>`_.
+
+The project as been employed for `OGC Testbed-15 - ML Thread <ogc-tb15-ml>`_ to demonstrate the use of Machine Learning
+interactions with OGC web standards in the context of natural resources applications. The advancements are reported
+through the `OGC Testbed-15: Machine Learning Engineering Report <ogc-tb15-ml-er>`_.
+
+Developments are continued in `OGC Testbed-16 <ogc-tb16>`_ to improve methodologies in order to provide better
+interoperable geospatial data processing in the areas of Earth Observation Application Packages.
 
 The project is furthermore developed through the *Data Analytics for Canadian Climate Services* (`DACCS`_) initiative.
 
 Weaver is a **prototype** implemented in Python with the `Pyramid`_ web framework.
 It is part of `PAVICS`_ and `Birdhouse`_ ecosystems.
 
+.. _ogc-tb14: https://www.ogc.org/projects/initiatives/testbed14
+.. _ogc-tb14-platform-er: http://docs.opengeospatial.org/per/18-050r1.html
+.. _ogc-tb15-ml: https://www.ogc.org/projects/initiatives/testbed15#MachineLearning
+.. _ogc-tb15-ml-er: http://docs.opengeospatial.org/per/19-027r2.html
+.. _ogc-tb16: https://www.ogc.org/projects/initiatives/t-16
 .. _PAVICS: https://ouranosinc.github.io/pavics-sdi/index.html
 .. _Birdhouse: http://bird-house.github.io/
 .. _ESGF: https://esgf.llnl.gov/

docs/Makefile

@@ -7,22 +7,26 @@ SPHINXBUILD   = sphinx-build
 PAPER         =
 BUILDDIR      = build
 
-# User-friendly check for sphinx-build
-ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
-$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
-endif
-
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
 ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
 # the i18n builder cannot share the environment and doctrees with the others
 I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
 
+# User-friendly check for sphinx-build
+ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
+$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD \
+	environment variable to point to the full path of the '$(SPHINXBUILD)' executable. \
+	Alternatively you can add the directory with the executable to your PATH. If you do not have Sphinx installed, grab \
+	it from 'http://sphinx-doc.org/' \
+)
+endif
+
 .PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest coverage gettext
 
 help:
-	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "Please use 'make <target>' where <target> is one of"
 	@echo "  html       to make standalone HTML files"
 	@echo "  dirhtml    to make HTML files named index.html in directories"
 	@echo "  singlehtml to make a single large HTML file"
@@ -79,12 +83,14 @@ json:
 htmlhelp:
 	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
 	@echo
-	@echo "Build finished; now you can run HTML Help Workshop with the" 	      ".hhp project file in $(BUILDDIR)/htmlhelp."
+	@echo "Build finished; now you can run HTML Help Workshop with the \
+		.hhp project file in $(BUILDDIR)/htmlhelp."
 
 qthelp:
 	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
 	@echo
-	@echo "Build finished; now you can run "qcollectiongenerator" with the" 	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+	@echo "Build finished; now you can run "qcollectiongenerator" with the \
+		.qhcp project file in $(BUILDDIR)/qthelp, like this:"
 	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/weaver.qhcp"
 	@echo "To view the help file:"
 	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/weaver.qhc"
@@ -93,16 +99,17 @@ applehelp:
 	$(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp
 	@echo
 	@echo "Build finished. The help book is in $(BUILDDIR)/applehelp."
-	@echo "N.B. You won't be able to view it unless you put it in" 	      "~/Library/Documentation/Help or install it in your application" 	      "bundle."
+	@echo "N.B. You won't be able to view it unless you put it in \
+		~/Library/Documentation/Help or install it in your application bundle."
 
 devhelp:
 	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
 	@echo
 	@echo "Build finished."
 	@echo "To view the help file:"
-	@echo "# mkdir -p $$HOME/.local/share/devhelp/weaver"
-	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/weaver"
-	@echo "# devhelp"
+	@echo "\# mkdir -p $$HOME/.local/share/devhelp/weaver"
+	@echo "\# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/weaver"
+	@echo "\# devhelp"
 
 epub:
 	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
@@ -162,11 +169,11 @@ changes:
 linkcheck:
 	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
 	@echo
-	@echo "Link check complete; look for any errors in the above output " 	      "or in $(BUILDDIR)/linkcheck/output.txt."
+	@echo "Link check complete; look for any errors in the above output or in $(BUILDDIR)/linkcheck/output.txt."
 
 doctest:
 	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
-	@echo "Testing of doctests in the sources finished, look at the " 	      "results in $(BUILDDIR)/doctest/output.txt."
+	@echo "Testing of doctests in the sources finished, look at the results in $(BUILDDIR)/doctest/output.txt."
 
 coverage:
 	$(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage

docs/_extensions/doc_redirect.py

@@ -0,0 +1,119 @@
+# Inspired by following extension but used locally as there are not pypi package.
+# source: https://github.com/sphinx-contrib/redirects
+
+import os
+
+from sphinx.builders import html as builders
+from sphinx.util import logging
+
+LOGGER = logging.getLogger(__name__)
+
+TEMPLATE = """<html>
+  <head><meta http-equiv="refresh" content="0; url=%s"/></head>
+</html>
+"""
+
+
+def generate_redirects(app):
+    """
+    This extension allows to fake a link to the HTML page actually generated by an RST file which contains a literal.
+
+    *reference* to another RST file.
+
+    For example, suppose we have two RST (ie: ``file1.rst`` and ``file2.rst`` ). Within ``file1.rst`` we got:
+
+    .. code-block:: rst
+
+        see `file2`_ details
+
+        .. _file2: ./docs/file2.rst
+
+    Normally, the generated HTML will have an hyperlink named ``file2`` with a *literal* reference to ``file2.rst``.
+    This will result in HTTP Not Found (404) as it doesn't correspond to the generated ``file2.html``. Normally, this
+    can be fixed using the following directive:
+
+    .. code-block:: rst
+
+        :doc:`./docs/file2.rst`
+
+    But then, rendering on GitHub becomes literally this string with an hyperlink reference that doesn't lead to the
+    desired ``file2.rst`` (for quick documentation locally within the GitHub repository).
+
+    With this extension, if configuration is specified as follows, the HTML link is resolved by redirecting the literal
+    ``./file2.rst`` reference in the output HTML build directory to the desired ``file2.html`` generated (as required).
+
+    .. code-block:: python
+
+        doc_redirect_map = {
+            # mapping of: <actual-reference-in-rst> => <pointed-rst-generated-as-html>
+            "file2.rst": "file2.rst"
+        }
+
+    In other words, when ``file1.rst`` is viewed from GitHub, the literal relative path is used an the file is found,
+    while on ``Readthedocs`` (or when viewing locally in a browser), ``file1.html`` will contain a raw relative path to
+    where the pointed ``file2.html`` *should* be using corresponding base directories. This is demonstrated below:
+
+    .. code-block:: text
+
+        '<root>/docs/file1.rst' ===> '<build-html>/file1.html' (ref [file2]) ---> (raw '<root>/docs/file2.rst')
+                                                                                               |
+                                                                                               |
+        '<root>/docs/file2.rst' ===> '<build-html>/file2.html'   <------------------------------
+
+    .. note::
+
+        Literal RST file references must be relative to package root in other to be rendered correctly on GitHub.
+    """
+
+    if not isinstance(app.builder, builders.StandaloneHTMLBuilder):
+        ext = os.path.split(__file__)[-1].split(".")[0]
+        LOGGER.warning("Extension '{}' is only supported by the 'html' builder. Skipping...".format(ext))
+        return
+    if not isinstance(app.config.doc_redirect_map, dict) and len(app.config.doc_redirect_map):
+        LOGGER.info("Could not find doc redirect map")
+        return
+    in_suffix = None
+    if isinstance(app.config.source_suffix, list):
+        in_suffix = app.config.source_suffix[0]
+    elif isinstance(app.config.source_suffix, dict):
+        in_suffix = list(app.config.source_suffix.items())[0][0]
+    elif app.config.source_suffix:
+        in_suffix = app.config.source_suffix
+    if not in_suffix:
+        in_suffix = ".rst"
+
+    for from_path, to_path in app.config.doc_redirect_map.items():
+        LOGGER.debug("Redirecting [%s] -> [%s]" % (from_path, to_path))
+
+        rst_path = from_path
+        if not rst_path.endswith(in_suffix):
+            rst_path = rst_path + in_suffix
+        html_path = from_path.replace(in_suffix, ".html")
+        to_path_prefix = "..%s" % os.path.sep * (
+            len(html_path.split(os.path.sep)) - 1)
+        to_path = to_path_prefix + to_path.replace(in_suffix, ".html")
+        if not to_path.endswith(".html"):
+            to_path = to_path + ".html"
+        LOGGER.debug("RST  [%s] -> [%s]" % (rst_path, to_path))
+        LOGGER.debug("HTML [%s] -> [%s]" % (html_path, to_path))
+
+        redirected_rst_file = os.path.join(app.builder.outdir, rst_path)
+        redirected_html_file = os.path.join(app.builder.outdir, html_path)
+        redirected_directory = os.path.dirname(redirected_html_file)
+        if not os.path.exists(redirected_directory):
+            os.makedirs(redirected_directory)
+
+        # create unless it already exists (eg: same directory level, config map is redundant)
+        if not os.path.exists(redirected_html_file):
+            # if using a direct call with .html extension, it will still work as if calling the .rst
+            with open(redirected_html_file, "w") as f:
+                f.write(TEMPLATE % to_path)
+        if not os.path.exists(redirected_rst_file):
+            # point to the .rst that would be reach by clicking the literal reference
+            # by faking an .html file redirect
+            os.symlink(redirected_html_file, redirected_rst_file)
+
+
+def setup(app):
+    app.add_config_value("doc_redirect_map", {}, "env", dict)
+    app.connect("builder-inited", generate_redirects)

docs/_static/.gitignore

@@ -0,0 +1,3 @@
+# make this directory available as it is referenced by some extensions
+*.*
+!.gitignore

docs/_templates/autoapi/module.rst

@@ -0,0 +1,15 @@
+.. see original here: https://github.com/readthedocs/sphinx-autoapi/blob/master/autoapi/templates/index.rst
+
+Source Code
+=============
+
+This page contains reference documentation of the source code.
+
+.. toctree::
+   :titlesonly:
+
+   {% for page in pages %}
+   {% if page.top_level_object and page.display %}
+   {{ page.include_path }}
+   {% endif %}
+   {% endfor %}