using nbsphinx for notebooks (#754)

* using nbsphinx for notebooks

* added binder config

* update dependencies for nbsphinx build

* include licence text

* update code formatting in docs

.github/workflows/main.yml

@@ -19,8 +19,13 @@ jobs:
       name: Setup Python ${{ matrix.python-version }}
       with:
         python-version: ${{ matrix.python-version }}
+    - name: Install packages
+      run: |
+        sudo apt-get -y install pandoc
+      if: matrix.python-version == 3.6
     - name: Install requirements 📦
       run: |
+        pip3 install -e .
         pip3 install -r requirements.txt
         pip3 install -r requirements-dev.txt
         echo "LXML => $LXML"

.gitignore

@@ -27,3 +27,6 @@ tile.jpg
 /.pydevproject
 /.settings/
 /env27/
+
+# notebooks
+.ipynb_checkpoints

binder/environment.yml

@@ -0,0 +1,9 @@
+# conda env create -f environment.yml
+name: owslib
+channels:
+  - conda-forge
+  - defaults
+dependencies:
+  - pip
+  - lxml
+  - owslib>=0.23

binder/postBuild

@@ -0,0 +1 @@
+python setup.py install

docs/conf.py

@@ -22,7 +22,13 @@
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = []
+extensions = [
+    "nbsphinx",
+]
+
+# extension nbspinx
+# nbsphinx_timeout = 600
+# nbsphinx_execute = "auto"
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']

docs/en/credits.rst

@@ -0,0 +1,7 @@
+Credits
+=======
+
+.. include:: ../../AUTHORS.rst
+
+
+.. include:: ../../CHANGES.rst

docs/en/development.rst

@@ -0,0 +1,29 @@
+Development
+===========
+
+The OWSLib wiki is located at https://github.com/geopython/OWSLib/wiki
+
+The OWSLib source code is available at https://github.com/geopython/OWSLib
+
+You can find out about software metrics at the OWSLib OpenHub page at https://www.openhub.net/p/OWSLib.
+
+Testing
+-------
+
+.. code-block:: bash
+
+   python setup.py test
+
+Or ...
+
+.. code-block:: bash
+
+    # install requirements
+    pip install -r requirements.txt
+    pip install -r requirements-dev.txt # needed for tests only
+
+    # run tests
+    python -m pytest
+
+    # additional pep8 tests
+    pep8 owslib/wmts.py

docs/en/examples.rst

@@ -0,0 +1,21 @@
+.. _examples:
+
+Examples
+========
+
+You can try these notebook online using Binder, or view the notebooks on NBViewer.
+
+.. image:: https://mybinder.org/badge_logo.svg
+   :target: https://mybinder.org/v2/gh/geopython/OWSLib.git/master?filepath=notebooks
+   :alt: Binder Launcher
+   :height: 20
+
+.. image:: https://raw.githubusercontent.com/jupyter/design/master/logos/Badges/nbviewer_badge.svg
+   :target: https://nbviewer.jupyter.org/github/geopython/OWSLib/tree/master/notebooks/
+   :alt: NBViewer
+   :height: 20
+
+.. toctree::
+   :maxdepth: 1
+
+   notebooks/examples/wms

docs/en/features.rst

@@ -0,0 +1,85 @@
+Features
+========
+
+Standards Support
+-----------------
+
++-----------------------+-----------------------------+
+| Standard              | Version(s)                  |
++=======================+=============================+
+| `OGC WMS`_            | 1.1.1, 1.3.0                |
++-----------------------+-----------------------------+
+| `OGC WFS`_            | 1.0.0, 1.1.0, 2.0.0, 3.0    |
++-----------------------+-----------------------------+
+| `OGC WCS`_            | 1.0.0, 1.1.0, 2.0, 2.0.1    |
++-----------------------+-----------------------------+
+| `OGC WMC`_            | 1.1.0                       |
++-----------------------+-----------------------------+
+| `OGC SOS`_            | 1.0.0, 2.0.0                |
++-----------------------+-----------------------------+
+| `OGC SensorML`_       | 1.0.1                       |
++-----------------------+-----------------------------+
+| `OGC CSW`_            | 2.0.2                       |
++-----------------------+-----------------------------+
+| `OGC WPS`_            | 1.0.0                       |
++-----------------------+-----------------------------+
+| `OGC Filter`_         | 1.1.0                       |
++-----------------------+-----------------------------+
+| `OGC OWS Common`_     | 1.0.0, 1.1.0, 2.0           |
++-----------------------+-----------------------------+
+| `OGC OWS Context`_    | 1.0.0 (alpha/under-review)  |
++-----------------------+-----------------------------+
+| `NASA DIF`_           | 9.7                         |
++-----------------------+-----------------------------+
+| `FGDC CSDGM`_         | 1998                        |
++-----------------------+-----------------------------+
+| `ISO 19139`_          | 2007                        |
++-----------------------+-----------------------------+
+| `ISO 19139-2`_        | 2012                        |
++-----------------------+-----------------------------+
+| `Dublin Core`_        | 1.1                         |
++-----------------------+-----------------------------+
+| `Swiss GM03`_         | 2.3                         |
++-----------------------+-----------------------------+
+| `OGC WMTS`_           | 1.0.0                       |
++-----------------------+-----------------------------+
+| `WaterML`_            | 1.0, 1.1, 2.0               |
++-----------------------+-----------------------------+
+
+OGC API Support
+---------------
+
++---------------------------------------------------+
+| Standard                             | Version(s) |
++======================================+============+
+| `OGC API - Features - Part 1: Core`_ | 1.0        |
++--------------------------------------+------------+
+| `OGC API - Records - Part 1: Core`_  | draft      |
++--------------------------------------+------------+
+
+.. _`OGC WMS`: https://www.opengeospatial.org/standards/wms
+.. _`OGC WFS`: https://www.opengeospatial.org/standards/wfs
+.. _`OGC WCS`: https://www.opengeospatial.org/standards/wcs
+.. _`OGC WMC`: https://www.opengeospatial.org/standards/wmc
+.. _`OGC WPS`: https://www.opengeospatial.org/standards/wps
+.. _`OGC SOS`: https://www.opengeospatial.org/standards/sos
+.. _`OGC O&M`: https://www.opengeospatial.org/standards/om
+.. _`OGC WaterML2.0`: https://www.opengeospatial.org/standards/waterml
+.. _`OGC SensorML`: https://www.opengeospatial.org/standards/sensorml
+.. _`OGC CSW`: https://www.opengeospatial.org/standards/cat
+.. _`OGC WMTS`: https://www.opengeospatial.org/standards/wmts
+.. _`OGC Filter`: https://www.opengeospatial.org/standards/filter
+.. _`OGC OWS Common`: https://www.opengeospatial.org/standards/common
+.. _`OGC OWS Context`: https://www.opengeospatial.org/standards/owc
+.. _`NASA DIF`: https://earthdata.nasa.gov/esdis/eso/standards-and-references/directory-interchange-format-dif-standard
+.. _`FGDC CSDGM`: https://www.fgdc.gov/metadata/csdgm-standard
+.. _`ISO 19115`: https://www.iso.org/standard/26020.html
+.. _`ISO 19139`: https://www.iso.org/standard/32557.html
+.. _`ISO 19139-2`: https://www.iso.org/standard/57104.html
+.. _`Dublin Core`: https://www.dublincore.org/
+.. _`CIA.vc`: http://cia.vc/stats/project/OWSLib
+.. _`WaterML`: http://his.cuahsi.org/wofws.html#waterml
+.. _`Swiss GM03`: https://www.geocat.admin.ch/en/dokumentation/gm03.html
+.. _`OGC API`: https://ogcapi.ogc.org
+.. _`OGC API - Features - Part 1: Core`: https://docs.opengeospatial.org/is/17-069r3/17-069r3.html
+.. _`OGC API - Records - Part 1: Core`: https://github.com/opengeospatial/ogcapi-records