Skip to content

GitLab

Verified Commit 57a0413c authored by Hill, Clifford (Contractor) John's avatar Hill, Clifford (Contractor) John
Browse files

Converted docs from rst to md. 


Signed-off-by: Hill, Clifford (Contractor) John's avatarCliff Hill <chill@contractor.usgs.gov>
parent 5fcf7050
Hide whitespace changes
Inline Side-by-side
DISCLAIMER.md 0 → 100644
View file @ 57a0413c
Disclaimer
==========
This software is preliminary or provisional and is subject to revision. It is
being provided to meet the need for timely best science. The software has not
received final approval by the U.S. Geological Survey (USGS). No warranty,
expressed or implied, is made by the USGS or the U.S. Government as to the
functionality of the software and related material nor shall the fact of release
constitute any such warranty. The software is provided on the condition that
neither the USGS nor the U.S. Government shall be held liable for any damages
resulting from the authorized or unauthorized use of the software.
DISCLAIMER.rst deleted 100644 → 0
View file @ 5fcf7050
Preliminary (provisional) data, information, or software
========================================================
This software is preliminary or provisional and is subject to revision.
It is being provided to meet the need for timely best science. The
software has not received final approval by the U.S. Geological Survey
(USGS). No warranty, expressed or implied, is made by the USGS or the
U.S. Government as to the functionality of the software and related
material nor shall the fact of release constitute any such warranty. The
software is provided on the condition that neither the USGS nor the U.S.
Government shall be held liable for any damages resulting from the
authorized or unauthorized use of the software.
LICENSE.rst → LICENSE.md
View file @ 57a0413c
License
=======
Unless otherwise noted, This project is in the public domain in the
United States because it contains materials that originally came from
the United States Geological Survey, an agency of the United States
Department of Interior. For more information, see the official USGS
copyright policy at
Unless otherwise noted, This project is in the public domain in the United
States because it contains materials that originally came from the United
States Geological Survey, an agency of the United States Department of
Interior. For more information, see the official USGS copyright policy at
https://www.usgs.gov/information-policies-and-instructions/copyrights-and-credits
Additionally, we waive copyright and related rights in the work
worldwide through the CC0 1.0 Universal public domain dedication.
CC0 1.0 Universal Summary
-------------------------
This is a human-readable summary of the `Legal Code (read the full
text) <https://creativecommons.org/publicdomain/zero/1.0/legalcode>`__.
This is a human-readable summary of the
[Legal Code (read the full text)][1].
### No Copyright
No Copyright
~~~~~~~~~~~~
The person who associated a work with this deed has dedicated the work to
the public domain by waiving all of his or her rights to the work worldwide
under copyright law, including all related and neighboring rights, to the
extent allowed by law.
The person who associated a work with this deed has dedicated the work
to the public domain by waiving all of his or her rights to the work
worldwide under copyright law, including all related and neighboring
rights, to the extent allowed by law.
You can copy, modify, distribute and perform the work, even for commercial
purposes, all without asking permission.
You can copy, modify, distribute and perform the work, even for
commercial purposes, all without asking permission.
Other Information
~~~~~~~~~~~~~~~~~
### Other Information
In no way are the patent or trademark rights of any person affected by
CC0, nor are the rights that other persons may have in the work or in
how the work is used, such as publicity or privacy rights.
In no way are the patent or trademark rights of any person affected by CC0,
nor are the rights that other persons may have in the work or in how the
work is used, such as publicity or privacy rights.
Unless expressly stated otherwise, the person who associated a work with
this deed makes no warranties about the work, and disclaims liability
for all uses of the work, to the fullest extent permitted by applicable
law. When using or citing the work, you should not imply endorsement by
the author or the affirmer.
this deed makes no warranties about the work, and disclaims liability for
all uses of the work, to the fullest extent permitted by applicable law.
When using or citing the work, you should not imply endorsement by the
author or the affirmer.
[1]: https://creativecommons.org/publicdomain/zero/1.0/legalcode
README.md 0 → 100644
View file @ 57a0413c
pygeoapi-plugin-cookiecutter
============================
Cookiecutter project for creating new pygeoapi-plugins.
Prerequisites
-------------
- This project obviously requires
[Cookiecutter](https://github.com/audreyr/cookiecutter) to be
installed in order to be used.
- The user must have SSH access to the external USGS GitLab instance
at `code.usgs.gov`.
- The project that is created requires the use of
[conda](https://www.anaconda.com), and will expect that tool to be
available.
- Other than the use of [conda](https://www.anaconda.com) rather than
Poetry for dependency management, this follows the patterns defined
in [Hypermodern
Python](https://medium.com/@cjolowicz/hypermodern-python-d44485d9d769).
- This project can be used with [direnv](https://direnv.net/) to
automatically configure and run the
[conda](https://www.anaconda.com) environment it creates.
Usage
-----
``` {.sourceCode .console}
$ cookiecutter git+ssh://git@code.usgs.gov/wma/nhgf/pygeoapi-plugin-cookiecutter.git
```
Setup
-----
### With [direnv](https://direnv.net/)
When you first enter the directory, with [direnv](https://direnv.net/)
enabled, you will need to run:
``` {.sourceCode .console}
$ direnv allow
```
### Without [direnv](https://direnv.net/)
If you do not use [direnv](https://direnv.net/), it is possible to get
the development environment running with the following:
``` {.sourceCode .console}
$ conda env create -f environment.yml
$ conda develop -n {{cookiecutter.project_name}} src
$ conda activate {{cookiecutter.project_name}}
$ pip install -r requirements.dev
```
It is important to get [preccommit](https://pre-commit.com/) enabled on
the project, to ensure that certain standards are always met on a git
commit. With several of these, it might fail if files are changed, but
it will change them, and trying the commit a second time will actually
work.
### Git hook configuration
``` {.sourceCode .console}
$ pre-commit install --install-hooks
```
### Testing
[Nox](https://nox.thea.codes/) is used for testing everything, with
several sessions built-in. To run the full suite of tests, simply use:
``` {.sourceCode .console}
$ nox
```
The different sessions are:
- `pre-commit` -- validates that the
[preccommit](https://pre-commit.com/) checks all come back clean.
- `safety` -- validates the [Safety](https://github.com/pyupio/safety)
of all production dependencies.
- `mypy` -- validates the type-hints for the application using
[mypy](http://mypy-lang.org/).
- `tests` -- runs all [pytest](https://docs.pytest.org/en/latest/)
tests.
- `typeguard` -- runs all [pytest](https://docs.pytest.org/en/latest/)
tests, validates with
[Typeguard](https://github.com/agronholm/typeguard).
- `xdoctest` -- runs any and all documentation examples with
[xdoctest](https://github.com/Erotemic/xdoctest).
- `docs-build` -- builds the full set of generated API docs with
[Sphinx](http://www.sphinx-doc.org/).
These can be run individually with the following command:
``` {.sourceCode .console}
$ nox -s <session>
```
Replace `<session>` with the name of the session give above, i.e.:
``` {.sourceCode .console}
$ nox -s mypy
```
You can also simply run [pytest](https://docs.pytest.org/en/latest/)
tests, by using the command:
``` {.sourceCode .console}
$ pytest tests
```
### Dependencies
Production dependencies are duplicated, in both `requirements.txt` and
`environment.yml` due to how [conda](https://www.anaconda.com) does not
work with the `requirements.txt` file. It is necessary for both files to
be updated as dependencies are added.
Development dependencies are contained in `requirements.dev`.
### Version Management
Warning:
: Do not set the initial version to `0.0.0`. This will break, due to
an unknown bug in
[Bump2version](https://github.com/c4urself/bump2version) at this
time.
The projects made by this cookiecutter use
[Bump2version](https://github.com/c4urself/bump2version) for version
management. The default version that the project starts with is a
developmental version, `0.0.1-dev0`. In github, this should be
auto-incremented on each commit to the next dev build number. To manage
the version changes yourself, you can use the
[Bump2version](https://github.com/c4urself/bump2version) command:
``` {.sourceCode .console}
$ bump2version <part>
```
Where `<part>` is one of:
- `major`
- `minor`
- `patch`
- `build`
Note:
: This makes a `dev` version, which does not write a tag into git. It
is just useful for development purposes and not the version that is
recommended for a release version. The version string will be
formatted as: `<major>.<minor>.<patch>-dev<build>`
To do a production release, use the command:
``` {.sourceCode .console}
$ bump2version --tag release
```
This will add a tag in the git repository noting the version.
Note:
: The version string for this will be: `<major>.<minor>.<patch>`
Features
--------
- Packaging and dependency management with
[conda](https://www.anaconda.com)
- Test automation with [Nox](https://nox.thea.codes/)
- Linting with [preccommit](https://pre-commit.com/) and
[Flake8](http://flake8.pycqa.org)
- Continuous integration with [GitHub
Actions](https://github.com/features/actions) or
[Travis-CI](https://travis-ci.com)
- Documentation with [Sphinx](http://www.sphinx-doc.org/) and [Read
the Docs](https://readthedocs.org/)
- Automated uploads to [PyPI](https://pypi.org/) and
[TestPyPI](https://test.pypi.org/)
- Automated release notes with [Release
Drafter](https://github.com/release-drafter/release-drafter)
- Automated dependency updates with
[Dependabot](https://dependabot.com/)
- Code formatting with [Black](https://github.com/psf/black) and
[Prettier](https://prettier.io/)
- Testing with [pytest](https://docs.pytest.org/en/latest/)
- Code coverage with [Coverageppy](https://coverage.readthedocs.io/)
- Coverage reporting with [Codecov](https://codecov.io/)
- Command-line interface with
[Click](https://click.palletsprojects.com/)
- Static type-checking with [mypy](http://mypy-lang.org/)
- Runtime type-checking with
[Typeguard](https://github.com/agronholm/typeguard)
- Security audit with [Bandit](https://github.com/PyCQA/bandit) and
[Safety](https://github.com/pyupio/safety)
- Check documentation examples with
[xdoctest](https://github.com/Erotemic/xdoctest)
- Generate API documentation with
[autodoc](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html)
and
[napoleon](https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html)
- Generate command-line reference with
[sphinxcclick](https://sphinx-click.readthedocs.io/)
- Manage project labels with [GitHub
Labeler](https://github.com/marketplace/actions/github-labeler)
- Manage project versions with
[Bump2version](https://github.com/c4urself/bump2version)
- Automatic loading/unloading of [conda](https://www.anaconda.com)
environment with [direnv](https://direnv.net/)
The template supports Python 3.8 and 3.9.
README.rst deleted 100644 → 0
View file @ 5fcf7050
============================
pygeoapi-plugin-cookiecutter
============================
Cookiecutter project for creating new pygeoapi-plugins.
Prerequisites
=============
- This project obviously requires Cookiecutter_ to be installed in order to be used.
- The user must have SSH access to the external USGS GitLab instance at ``code.usgs.gov``.
- The project that is created requires the use of conda_, and will expect that tool to be available.
- Other than the use of conda_ rather than Poetry for dependency management, this follows the patterns defined in `Hypermodern Python`_.
- This project can be used with direnv_ to automatically configure and run the conda_ environment it creates.
Usage
=====
.. code:: console
$ cookiecutter git+ssh://git@code.usgs.gov/wma/nhgf/pygeoapi-plugin-cookiecutter.git
Setup
=====
With direnv_
------------
When you first enter the directory, with direnv_ enabled, you will need to run:
.. code:: console
$ direnv allow
Without direnv_
---------------
If you do not use direnv_, it is possible to get the development environment running with the
following:
.. code:: console
$ conda env create -f environment.yml
$ conda develop -n {{cookiecutter.project_name}} src
$ conda activate {{cookiecutter.project_name}}
$ pip install -r requirements.dev
It is important to get pre-commit_ enabled on the project, to ensure that certain standards
are always met on a git commit. With several of these, it might fail if files are changed, but
it will change them, and trying the commit a second time will actually work.
Git hook configuration
----------------------
.. code:: console
$ pre-commit install --install-hooks
Testing
-------
Nox_ is used for testing everything, with several sessions built-in. To run the full suite of
tests, simply use:
.. code:: console
$ nox
The different sessions are:
* ``pre-commit`` -- validates that the pre-commit_ checks all come back clean.
* ``safety`` -- validates the Safety_ of all production dependencies.
* ``mypy`` -- validates the type-hints for the application using mypy_.
* ``tests`` -- runs all pytest_ tests.
* ``typeguard`` -- runs all pytest_ tests, validates with Typeguard_.
* ``xdoctest`` -- runs any and all documentation examples with xdoctest_.
* ``docs-build`` -- builds the full set of generated API docs with Sphinx_.
These can be run individually with the following command:
.. code:: console
$ nox -s <session>
Replace ``<session>`` with the name of the session give above, i.e.:
.. code:: console
$ nox -s mypy
You can also simply run pytest_ tests, by using the command:
.. code:: console
$ pytest tests
Dependencies
------------
Production dependencies are duplicated, in both ``requirements.txt`` and ``environment.yml`` due
to how conda_ does not work with the ``requirements.txt`` file. It is necessary for both files
to be updated as dependencies are added.
Development dependencies are contained in ``requirements.dev``.
Version Management
------------------
Warning:
Do not set the initial version to ``0.0.0``. This will break, due to an unknown bug in
Bump2version_ at this time.
The projects made by this cookiecutter use Bump2version_ for version management. The default
version that the project starts with is a developmental version, ``0.0.1-dev0``. In github, this
should be auto-incremented on each commit to the next dev build number. To manage the version
changes yourself, you can use the Bump2version_ command:
.. code:: console
$ bump2version <part>
Where ``<part>`` is one of:
* ``major``
* ``minor``
* ``patch``
* ``build``
Note:
This makes a ``dev`` version, which does not write a tag into git. It is just useful for
development purposes and not the version that is recommended for a release version. The
version string will be formatted as: ``<major>.<minor>.<patch>-dev<build>``
To do a production release, use the command:
.. code:: console
$ bump2version --tag release
This will add a tag in the git repository noting the version.
Note:
The version string for this will be: ``<major>.<minor>.<patch>``
Features
========
.. features-begin
- Packaging and dependency management with `conda`_
- Test automation with Nox_
- Linting with pre-commit_ and Flake8_
- Continuous integration with `GitHub Actions`_ or `Travis-CI`_
- Documentation with Sphinx_ and `Read the Docs`_
- Automated uploads to PyPI_ and TestPyPI_
- Automated release notes with `Release Drafter`_
- Automated dependency updates with Dependabot_
- Code formatting with Black_ and Prettier_
- Testing with pytest_
- Code coverage with Coverage.py_
- Coverage reporting with Codecov_
- Command-line interface with Click_
- Static type-checking with mypy_
- Runtime type-checking with Typeguard_
- Security audit with Bandit_ and Safety_
- Check documentation examples with xdoctest_
- Generate API documentation with autodoc_ and napoleon_
- Generate command-line reference with sphinx-click_
- Manage project labels with `GitHub Labeler`_
- Manage project versions with Bump2version_
- Automatic loading/unloading of conda_ environment with direnv_
The template supports Python 3.8 and 3.9.
.. features-end
.. references-begin
.. _Bandit: https://github.com/PyCQA/bandit
.. _Black: https://github.com/psf/black
.. _Bump2version: https://github.com/c4urself/bump2version
.. _Click: https://click.palletsprojects.com/
.. _Codecov: https://codecov.io/
.. _conda: https://www.anaconda.com
.. _Cookiecutter: https://github.com/audreyr/cookiecutter
.. _Coverage.py: https://coverage.readthedocs.io/
.. _Dependabot: https://dependabot.com/
.. _direnv: https://direnv.net/
.. _Flake8: http://flake8.pycqa.org
.. _GitHub Actions: https://github.com/features/actions
.. _Hypermodern Python: https://medium.com/@cjolowicz/hypermodern-python-d44485d9d769
.. _Nox: https://nox.thea.codes/
.. _Prettier: https://prettier.io/
.. _PyPI: https://pypi.org/
.. _Read the Docs: https://readthedocs.org/
.. _Release Drafter: https://github.com/release-drafter/release-drafter
.. _Safety: https://github.com/pyupio/safety
.. _Sphinx: http://www.sphinx-doc.org/
.. _TestPyPI: https://test.pypi.org/
.. _Typeguard: https://github.com/agronholm/typeguard
.. _autodoc: https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html
.. _mypy: http://mypy-lang.org/
.. _napoleon: https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html
.. _pre-commit: https://pre-commit.com/
.. _pytest: https://docs.pytest.org/en/latest/
.. _sphinx-click: https://sphinx-click.readthedocs.io/
.. _xdoctest: https://github.com/Erotemic/xdoctest
.. _GitHub Labeler: https://github.com/marketplace/actions/github-labeler
.. _Travis-CI: https://travis-ci.com
.. references-end
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment