update contributor guidelines and dev docs (#2032)

CONTRIBUTING.md

@@ -65,6 +65,7 @@ Your contribution will be under our [license](https://github.com/geopython/pygeo
 * Pull requests may include copyright in the source code header by the contributor if the contribution is significant or the contributor wants to claim copyright on their contribution.
 * All contributors shall be listed at https://github.com/geopython/pygeoapi/graphs/contributors
 * Unclaimed copyright, by default, is assigned to the main copyright holders as specified in https://github.com/geopython/pygeoapi/blob/master/LICENSE.md
+* further notes can be found in the `documentation <https://docs.pygeoapi.io/en/latest/development.html#testing>`_
 
 ### Version Control Branching
 
@@ -89,16 +90,23 @@ Your contribution will be under our [license](https://github.com/geopython/pygeo
       while, __make sure you rebase or merge to latest ``master``__ to ensure a
         speedier resolution.
 
+### Testing
+
+* testing is performed using `pytest <https://pytest.org>`_ and covers all major components (API core, providers, formatters, managers, etc.)
+* additional information can be found in the `documentation <https://docs.pygeoapi.io/en/latest/development.html#testing>`_
+
+
 ### Documentation
 
 * documentation is managed in `docs/`, in reStructuredText format
 * [Sphinx](https://www.sphinx-doc.org) is used to generate the documentation
 * See the [reStructuredText Primer](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html) on rST markup and syntax
+* additional information can be found in the `documentation <https://docs.pygeoapi.io/en/latest/development.html#building-the-documentation>`_
 
 
 ### Wiki
 
-* the [pygeoapi wiki](https://github.com/geopython/pygeoapi/wiki) provides working level documentation
+* the [pygeoapi wiki](https://github.com/geopython/pygeoapi/wiki) provides working level documentation and various community resources
 
 
 ### Code Formatting
@@ -107,7 +115,8 @@ Your contribution will be under our [license](https://github.com/geopython/pygeo
 * pygeoapi follows the [PEP-8](http://www.python.org/dev/peps/pep-0008/) guidelines
 * 80 characters
 * spaces, not tabs
-* pygeoapi, instead of PyGeoAPI, pygeoAPI, etc.
+* pygeoapi, NOT PyGeoAPI, pygeoAPI, etc.
+* additional information can be found in the `documentation <https://docs.pygeoapi.io/en/latest/development.html#linting>`_
 
 ## Suggesting Enhancements
 

docs/source/contributing.rst

@@ -3,46 +3,5 @@
 Contributing
 ============
 
-Building the documentation
---------------------------
-
-To build the documentation in pygeoapi we use `Sphinx`_. The documentation is located in the docs folder.
-
-.. note::
-   For the following instructions to work, you must be located in the root folder of pygeoapi.
-
-Install the dependencies necessary for building the documentation using the following command:
-
-.. code-block:: bash
-
-   pip3 install -r docs/requirements.txt
-
-After installing the requirements, build the documentation using the ``sphinx-build`` command:
-
-.. code-block:: bash
-
-   sphinx-build -M html docs/source docs/build
-
-
-Or using the following ``make`` command:
-
-.. code-block:: bash
-
-   make -C docs html
-
-After building the documentation, the folder ``docs/build`` will contain the website generated with the documentation. 
-Add the folder to a web server or open the file ``docs/build/html/index.html`` file in a web browser to see the contents of the documentation.
-
-The documentation is hosted on `readthedocs`_. It is automatically generated from the contents of the ``master`` branch on GitHub.
-
-The file ``.readthedocs.yaml`` contains the configuration of the readthedocs build. Refer to the `readthedocs configuration file`_ documentation for more information.
-
-Contributing GitHub page
-------------------------
-
 Please see the `Contributing page <https://github.com/geopython/pygeoapi/blob/master/CONTRIBUTING.md>`_
 for information on contributing to the project.
-
-.. _`Sphinx`: https://www.djangoproject.com
-.. _`readthedocs`: https://docs.readthedocs.io/en/stable/index.html
-.. _readthedocs configuration file: https://docs.readthedocs.io/en/stable/config-file/v2.html

docs/source/development.rst

@@ -8,6 +8,15 @@ Codebase
 
 The pygeoapi codebase exists at https://github.com/geopython/pygeoapi.
 
+Pull Requests and GitHub Actions
+--------------------------------
+
+A given GitHub Pull Request is evaluated against the following GitHub actions:
+
+- main: mainline testing harness (as defined in ``tests``)
+- flake8: code linting
+- docs: documentation updates (for files updated in ``docs/**.rst``)
+- vulnerabilities: Trivy vulnerability scanning
 
 Testing
 -------
@@ -22,6 +31,78 @@ Tests can be run locally as part of development workflow.  They are also run on
 To run all tests, simply run ``pytest`` in the repository.  To run a specific test file,
 run ``pytest tests/api/test_itemtypes.py``, for example.
 
+Some provider tests are subject to external service provisioning and setup (i.e Elasticsearch,
+PostgreSQL).  See the `GitHub Action main workflow <https://github.com/geopython/pygeoapi/blob/master/.github/workflows/main.yml>`_
+to review the setups taken in order to run provider tests requiring additional infrastructure.
+
+.. _pre-commit:
+
+Linting
+-------
+
+pygeoapi follows PEP8 for linting Python source code.  All commits and GitHub Pull Requests
+perform ``flake8`` linting compliance prior to approval and/or merge into the codebase.  Running linting
+compliance prior to submitting a GitHub Pull Request is recommended.
+
+Using flake8
+^^^^^^^^^^^^
+
+Simply running `flake8` against the repository tree will assess the code for linting compliance.
+
+.. note::
+
+   Ensure flake8 is installed (``pip3 install flake8`` or ``pip3 install -r requirements.txt``)
+
+Using pre-commit
+^^^^^^^^^^^^^^^^
+
+You may optionally use `pre-commit`_ in order to check for linting and other static issues
+before committing changes. Pygeoapi's repo includes a ``.pre-commit.yml``
+file, check the pre-commit docs on how to set it up - in a nutshell:
+
+- pre-commit is mentioned in pygeoapi's ``requirements-dev.txt`` file, so it will be included
+  when you pip install those
+- run ``pre-commit install`` once in order to install its git commit hooks.
+- optionally, run ``pre-commit run --all-files``, which will run all pre-commit hooks for all files in the repo.
+  This also prepares the pre-commit environment.
+- from now on, whenever you do a ``git commit``, the pre-commit hooks will run and the commit
+  will only be done if all checks pass
+
+Building the documentation
+--------------------------
+
+To build the documentation in pygeoapi we use `Sphinx`_. The documentation is located in the docs folder.
+
+.. note::
+   For the following instructions to work, you must be located in the root folder of pygeoapi.
+
+Install the dependencies necessary for building the documentation using the following command:
+
+.. code-block:: bash
+
+   pip3 install -r docs/requirements.txt
+
+After installing the requirements, build the documentation using the ``sphinx-build`` command:
+
+.. code-block:: bash
+
+   sphinx-build -M html docs/source docs/build
+
+
+Or using the following ``make`` command:
+
+.. code-block:: bash
+
+   make -C docs html
+
+After building the documentation, the folder ``docs/build`` will contain the website generated with the documentation. 
+Add the folder to a web server or open the file ``docs/build/html/index.html`` file in a web browser to see the contents of the documentation.
+
+The documentation is hosted on `Read the Docs`_. It is automatically generated from the contents of the ``master`` branch on GitHub.
+
+The file ``.readthedocs.yaml`` contains the configuration of the Read the Docs build. Refer to the `Read the Docs configuration file`_ documentation for more information.
+
+
 Working with Spatialite on OSX
 ------------------------------
 
@@ -66,24 +147,8 @@ Set the variable for the Spatialite library under OSX:
 
    SPATIALITE_LIBRARY_PATH=/usr/local/lib/mod_spatialite.dylib
 
-
+.. _`flake8`: https://flake8.pycqa.org
 .. _`GitHub Actions setup`: https://github.com/geopython/pygeoapi/blob/master/.github/workflows/main.yml
-
-
-Using pre-commit
-----------------
-
-You may optionally use `pre-commit`_ in order to check for linting and other static issues
-before committing changes. Pygeoapi's repo includes a ``.pre-commit.yml``
-file, check the pre-commit docs on how to set it up - in a nutshell:
-
-- pre-commit is mentioned in pygeoapi's ``requirements-dev.txt`` file, so it will be included
-  when you pip install those
-- run ``pre-commit install`` once in order to install its git commit hooks.
-- optionally, run ``pre-commit run --all-files``, which will run all pre-commit hooks for all files in the repo.
-  This also prepares the pre-commit environment.
-- from now on, whenever you do a ``git commit``, the pre-commit hooks will run and the commit
-  will only be done if all checks pass
-
-
-.. _pre-commit:
+.. _`Sphinx`: https://www.sphinx-doc.org
+.. _`Read the Docs`: https://docs.readthedocs.io/en/stable/index.html
+.. _`Read the Docs configuration file`: https://docs.readthedocs.io/en/stable/config-file/v2.html