From 3d12df031e9a20db668556e167aebc6857fb8244 Mon Sep 17 00:00:00 2001 From: Tom Kralidis Date: Mon, 30 Jun 2025 10:40:50 -0400 Subject: [PATCH 1/3] update contributor guidelines (#2032) --- CONTRIBUTING.md | 13 ++++- docs/source/contributing.rst | 41 -------------- docs/source/development.rst | 105 ++++++++++++++++++++++++++++------- 3 files changed, 96 insertions(+), 63 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d62a4a32c..6aa866b01 100644 --- a/CONTRIBUTING.md +++ b/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 `_ ### 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 peformed using `pytest `_ and covers all major components (API core, providers, formatters, managers, etc.) +* additional information can be found in the `documentation `_ + + ### 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 `_ ### 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 `_ ## Suggesting Enhancements diff --git a/docs/source/contributing.rst b/docs/source/contributing.rst index bbf17fe6a..d51db6afd 100644 --- a/docs/source/contributing.rst +++ b/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 `_ 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 \ No newline at end of file diff --git a/docs/source/development.rst b/docs/source/development.rst index 23bd8c6d5..e3b01e4da 100644 --- a/docs/source/development.rst +++ b/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 +- docss: 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 `_ +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 `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. + + 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.djangoproject.com +.. _`readthedocs`: https://docs.readthedocs.io/en/stable/index.html +.. _`readthedocs configuration file`: https://docs.readthedocs.io/en/stable/config-file/v2.html From d17efe5b7affa386534d2fceb828964e60e2f276 Mon Sep 17 00:00:00 2001 From: Tom Kralidis Date: Mon, 30 Jun 2025 16:24:40 -0400 Subject: [PATCH 2/3] fix PR comments --- docs/source/development.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/source/development.rst b/docs/source/development.rst index e3b01e4da..d783a9451 100644 --- a/docs/source/development.rst +++ b/docs/source/development.rst @@ -15,7 +15,7 @@ A given GitHub Pull Request is evaluated against the following GitHub actions: - main: mainline testing harness (as defined in ``tests``) - flake8: code linting -- docss: documentation updates (for files updated in ``docs/**.rst``) +- docs: documentation updates (for files updated in ``docs/**.rst``) - vulnerabilities: Trivy vulnerability scanning Testing @@ -98,9 +98,9 @@ Or using the following ``make`` command: 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 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 readthedocs build. Refer to the `readthedocs configuration file`_ documentation for more information. +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 @@ -149,6 +149,6 @@ Set the variable for the Spatialite library under OSX: .. _`flake8`: https://flake8.pycqa.org .. _`GitHub Actions setup`: https://github.com/geopython/pygeoapi/blob/master/.github/workflows/main.yml -.. _`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 +.. _`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 From 26e8d8f7d7b670b1569b8a1b0893b49acd1cba2b Mon Sep 17 00:00:00 2001 From: Tom Kralidis Date: Mon, 30 Jun 2025 16:40:49 -0400 Subject: [PATCH 3/3] fix typo --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6aa866b01..31520b7b5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -92,7 +92,7 @@ Your contribution will be under our [license](https://github.com/geopython/pygeo ### Testing -* testing is peformed using `pytest `_ and covers all major components (API core, providers, formatters, managers, etc.) +* testing is performed using `pytest `_ and covers all major components (API core, providers, formatters, managers, etc.) * additional information can be found in the `documentation `_