From 20532b221227495bc6caf78a3b6b3d6f62375659 Mon Sep 17 00:00:00 2001 From: "david.poulter" Date: Mon, 12 Aug 2024 14:03:25 +0100 Subject: [PATCH] Update to sphinx documentation, and documentation builder. --- CODE_OF_CONDUCT.md | 128 ---------------------------------- CODE_OF_CONDUCT.rst | 144 +++++++++++++++++++++++++++++++++++++++ CONTRIBUTING.md | 57 ---------------- CONTRIBUTING.rst | 71 +++++++++++++++++++ README.md | 3 - README.rst | 8 +++ SECURITY.md | 14 ---- SECURITY.rst | 22 ++++++ docs/code_of_conduct.rst | 1 + docs/contributing.rst | 1 + docs/index.rst | 12 ++-- docs/license.rst | 4 ++ docs/security.rst | 1 + 13 files changed, 259 insertions(+), 207 deletions(-) delete mode 100644 CODE_OF_CONDUCT.md create mode 100644 CODE_OF_CONDUCT.rst delete mode 100644 CONTRIBUTING.md create mode 100644 CONTRIBUTING.rst delete mode 100644 README.md create mode 100644 README.rst delete mode 100644 SECURITY.md create mode 100644 SECURITY.rst create mode 100644 docs/code_of_conduct.rst create mode 100644 docs/contributing.rst create mode 100644 docs/license.rst create mode 100644 docs/security.rst diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md deleted file mode 100644 index 22b8ee6..0000000 --- a/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,128 +0,0 @@ -# Contributor Covenant Code of Conduct - -## Our Pledge - -We as members, contributors, and leaders pledge to make participation in our -community a harassment-free experience for everyone, regardless of age, body -size, visible or invisible disability, ethnicity, sex characteristics, gender -identity and expression, level of experience, education, socio-economic status, -nationality, personal appearance, race, religion, or sexual identity -and orientation. - -We pledge to act and interact in ways that contribute to an open, welcoming, -diverse, inclusive, and healthy community. - -## Our Standards - -Examples of behavior that contributes to a positive environment for our -community include: - -* Demonstrating empathy and kindness toward other people -* Being respectful of differing opinions, viewpoints, and experiences -* Giving and gracefully accepting constructive feedback -* Accepting responsibility and apologizing to those affected by our mistakes, - and learning from the experience -* Focusing on what is best not just for us as individuals, but for the - overall community - -Examples of unacceptable behavior include: - -* The use of sexualized language or imagery, and sexual attention or - advances of any kind -* Trolling, insulting or derogatory comments, and personal or political attacks -* Public or private harassment -* Publishing others' private information, such as a physical or email - address, without their explicit permission -* Other conduct which could reasonably be considered inappropriate in a - professional setting - -## Enforcement Responsibilities - -Community leaders are responsible for clarifying and enforcing our standards of -acceptable behavior and will take appropriate and fair corrective action in -response to any behavior that they deem inappropriate, threatening, offensive, -or harmful. - -Community leaders have the right and responsibility to remove, edit, or reject -comments, commits, code, wiki edits, issues, and other contributions that are -not aligned to this Code of Conduct, and will communicate reasons for moderation -decisions when appropriate. - -## Scope - -This Code of Conduct applies within all community spaces, and also applies when -an individual is officially representing the community in public spaces. -Examples of representing our community include using an official e-mail address, -posting via an official social media account, or acting as an appointed -representative at an online or offline event. - -## Enforcement - -Instances of abusive, harassing, or otherwise unacceptable behavior may be -reported to the community leaders responsible for enforcement at -the author's email. -All complaints will be reviewed and investigated promptly and fairly. - -All community leaders are obligated to respect the privacy and security of the -reporter of any incident. - -## Enforcement Guidelines - -Community leaders will follow these Community Impact Guidelines in determining -the consequences for any action they deem in violation of this Code of Conduct: - -### 1. Correction - -**Community Impact**: Use of inappropriate language or other behavior deemed -unprofessional or unwelcome in the community. - -**Consequence**: A private, written warning from community leaders, providing -clarity around the nature of the violation and an explanation of why the -behavior was inappropriate. A public apology may be requested. - -### 2. Warning - -**Community Impact**: A violation through a single incident or series -of actions. - -**Consequence**: A warning with consequences for continued behavior. No -interaction with the people involved, including unsolicited interaction with -those enforcing the Code of Conduct, for a specified period of time. This -includes avoiding interactions in community spaces as well as external channels -like social media. Violating these terms may lead to a temporary or -permanent ban. - -### 3. Temporary Ban - -**Community Impact**: A serious violation of community standards, including -sustained inappropriate behavior. - -**Consequence**: A temporary ban from any sort of interaction or public -communication with the community for a specified period of time. No public or -private interaction with the people involved, including unsolicited interaction -with those enforcing the Code of Conduct, is allowed during this period. -Violating these terms may lead to a permanent ban. - -### 4. Permanent Ban - -**Community Impact**: Demonstrating a pattern of violation of community -standards, including sustained inappropriate behavior, harassment of an -individual, or aggression toward or disparagement of classes of individuals. - -**Consequence**: A permanent ban from any sort of public interaction within -the community. - -## Attribution - -This Code of Conduct is adapted from the [Contributor Covenant][homepage], -version 2.0, available at -https://www.contributor-covenant.org/version/2/0/code_of_conduct.html. - -Community Impact Guidelines were inspired by [Mozilla's code of conduct -enforcement ladder](https://github.com/mozilla/diversity). - -[homepage]: https://www.contributor-covenant.org - -For answers to common questions about this code of conduct, see the FAQ at -https://www.contributor-covenant.org/faq. Translations are available at -https://www.contributor-covenant.org/translations. diff --git a/CODE_OF_CONDUCT.rst b/CODE_OF_CONDUCT.rst new file mode 100644 index 0000000..50d1ef4 --- /dev/null +++ b/CODE_OF_CONDUCT.rst @@ -0,0 +1,144 @@ +Contributor Covenant Code of Conduct +==================================== + +Our Pledge +---------- + +We as members, contributors, and leaders pledge to make participation in +our community a harassment-free experience for everyone, regardless of +age, body size, visible or invisible disability, ethnicity, sex +characteristics, gender identity and expression, level of experience, +education, socio-economic status, nationality, personal appearance, +race, religion, or sexual identity and orientation. + +We pledge to act and interact in ways that contribute to an open, +welcoming, diverse, inclusive, and healthy community. + +Our Standards +------------- + +Examples of behavior that contributes to a positive environment for our +community include: + +- Demonstrating empathy and kindness toward other people +- Being respectful of differing opinions, viewpoints, and experiences +- Giving and gracefully accepting constructive feedback +- Accepting responsibility and apologizing to those affected by our + mistakes, and learning from the experience +- Focusing on what is best not just for us as individuals, but for the + overall community + +Examples of unacceptable behavior include: + +- The use of sexualized language or imagery, and sexual attention or + advances of any kind +- Trolling, insulting or derogatory comments, and personal or political + attacks +- Public or private harassment +- Publishing others’ private information, such as a physical or email + address, without their explicit permission +- Other conduct which could reasonably be considered inappropriate in a + professional setting + +Enforcement Responsibilities +---------------------------- + +Community leaders are responsible for clarifying and enforcing our +standards of acceptable behavior and will take appropriate and fair +corrective action in response to any behavior that they deem +inappropriate, threatening, offensive, or harmful. + +Community leaders have the right and responsibility to remove, edit, or +reject comments, commits, code, wiki edits, issues, and other +contributions that are not aligned to this Code of Conduct, and will +communicate reasons for moderation decisions when appropriate. + +Scope +----- + +This Code of Conduct applies within all community spaces, and also +applies when an individual is officially representing the community in +public spaces. Examples of representing our community include using an +official e-mail address, posting via an official social media account, +or acting as an appointed representative at an online or offline event. + +Enforcement +----------- + +Instances of abusive, harassing, or otherwise unacceptable behavior may +be reported to the community leaders responsible for enforcement at the +author’s email. All complaints will be reviewed and investigated +promptly and fairly. + +All community leaders are obligated to respect the privacy and security +of the reporter of any incident. + +Enforcement Guidelines +---------------------- + +Community leaders will follow these Community Impact Guidelines in +determining the consequences for any action they deem in violation of +this Code of Conduct: + +1. Correction +~~~~~~~~~~~~~ + +**Community Impact**: Use of inappropriate language or other behavior +deemed unprofessional or unwelcome in the community. + +**Consequence**: A private, written warning from community leaders, +providing clarity around the nature of the violation and an explanation +of why the behavior was inappropriate. A public apology may be +requested. + +2. Warning +~~~~~~~~~~ + +**Community Impact**: A violation through a single incident or series of +actions. + +**Consequence**: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, for a specified period of +time. This includes avoiding interactions in community spaces as well as +external channels like social media. Violating these terms may lead to a +temporary or permanent ban. + +3. Temporary Ban +~~~~~~~~~~~~~~~~ + +**Community Impact**: A serious violation of community standards, +including sustained inappropriate behavior. + +**Consequence**: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No +public or private interaction with the people involved, including +unsolicited interaction with those enforcing the Code of Conduct, is +allowed during this period. Violating these terms may lead to a +permanent ban. + +4. Permanent Ban +~~~~~~~~~~~~~~~~ + +**Community Impact**: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of +individuals. + +**Consequence**: A permanent ban from any sort of public interaction +within the community. + +Attribution +----------- + +This Code of Conduct is adapted from the `Contributor +Covenant `__, version 2.0, +available at +https://www.contributor-covenant.org/version/2/0/code_of_conduct.html. + +Community Impact Guidelines were inspired by `Mozilla’s code of conduct +enforcement ladder `__. + +For answers to common questions about this code of conduct, see the FAQ +at https://www.contributor-covenant.org/faq. Translations are available +at https://www.contributor-covenant.org/translations. \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index 0042277..0000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,57 +0,0 @@ -# How to contribute? - -## Branch structure - -Please create new features in `feature/` branch, when you are ready please create a pull request to -merge your feature into a `release/` branch. If there is no applicable release feel free to create -one. - -## Development environment - -Begin by collecting the repo from github. - -To contribute, you should be using `poetry` as your python package manager, see https://python-poetry.org for -installation instructions. Please wnsure that when you add or update dependencies, you use the `poetry add` or -`poetry add --group ` command to do so. If you do not, it is likely that the CI will reject your change. - -Once you have poetry installed, you should install the library with all it's dependencies: - -```shell -foo@bar:~$ poetry install -``` - -Then, activate the `pre-commit hooks` run: - -```shell -foo@bar:~$ poetry run install pre-commit -``` - -When you commit, the following checks will be run: - -- poetry-check (checks the conformity of the pyproject.toml and poetry.lock file) -- poetry-lock[^1] (ensures an up-to-date lock file) -- black[^1] (python style formatter) -- isort[^1] (python import order checker) -- ruff linter[^1] (python linter) -- mypy (python static type analysis) -- bandit (python SAST analyis) -- xenon (McCabe cyclomatc complexity analysis) -- sphinx (dry-run documentation build) - -You can disable the `pre-commit hooks` per commit with the flag `--no-verify` however all checks will be preformed in the CI. - -You can also (and are encouraged to) run the `pre-commit hooks` manually as often as you like with: - -```shell -foo@bar:~$ poetry run pre-commit run -a -``` - -## CI Environment - -The CI Enviroment runs the same checks as the `pre-commit hooks` on push[^2] plus the following additional checks: - -- audit (checks all dependencies for vulnerabilities) - -[^1]: These pre-commit hooks will attempt to fix the issue in place -[^2]: On CI, no checks perform code changes in place - diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst new file mode 100644 index 0000000..add11e9 --- /dev/null +++ b/CONTRIBUTING.rst @@ -0,0 +1,71 @@ +Contributing +============ + +Branch structure +---------------- + +Please create new features in ``feature/`` branch, when +you are ready please create a pull request to merge your feature into a +``release/`` branch. If there is no applicable +release feel free to create one. + +Development environment +----------------------- + +Begin by collecting the repo from github. + +To contribute, you should be using ``poetry`` as your python package +manager, see https://python-poetry.org for installation instructions. +Please wnsure that when you add or update dependencies, you use the +``poetry add`` or ``poetry add --group `` command to do so. +If you do not, it is likely that the CI will reject your change. + +Once you have poetry installed, you should install the library with all +it’s dependencies: + +.. code:: shell + + foo@bar:~$ poetry install + +Then, activate the ``pre-commit hooks`` run: + +.. code:: shell + + foo@bar:~$ poetry run install pre-commit + +When you commit, the following checks will be run: + +- poetry-check (checks the conformity of the pyproject.toml and + poetry.lock file) +- poetry-lock [1]_ (ensures an up-to-date lock file) +- black [1]_ (python style formatter) +- isort [1]_ (python import order checker) +- ruff linter [1]_ (python linter) +- mypy (python static type analysis) +- bandit (python SAST analyis) +- xenon (McCabe cyclomatc complexity analysis) +- sphinx (dry-run documentation build) + +You can disable the ``pre-commit hooks`` per commit with the flag +``--no-verify`` however all checks will be preformed in the CI. + +You can also (and are encouraged to) run the ``pre-commit hooks`` +manually as often as you like with: + +.. code:: shell + + foo@bar:~$ poetry run pre-commit run -a + +CI Environment +-------------- + +The CI Environment runs the same checks as the ``pre-commit hooks`` on +push [2]_ plus the following additional checks: + +- audit (checks all dependencies for vulnerabilities) + +.. [1] + These pre-commit hooks will attempt to fix the issue in place + +.. [2] + On CI, no checks perform code changes in place \ No newline at end of file diff --git a/README.md b/README.md deleted file mode 100644 index 4e24b1c..0000000 --- a/README.md +++ /dev/null @@ -1,3 +0,0 @@ -# esgf-playground-utils - -Common models, configuration and functionality for the ESGF-Playground. diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..537e8c8 --- /dev/null +++ b/README.rst @@ -0,0 +1,8 @@ +esgf-playground-utils +--------------------- + +Common models, configuration and functionality for the ESGF-Playground. + +Please read this `documentation `__ +in GitHub. + diff --git a/SECURITY.md b/SECURITY.md deleted file mode 100644 index 9790723..0000000 --- a/SECURITY.md +++ /dev/null @@ -1,14 +0,0 @@ -# Security Policy - -## Supported Versions - -No version is currently supported as this package is for experimentation. - -| Version | Supported | -| ------- | ------------------ | -| 0.3.x | :white_check_mark: | -| 0.2.x | :x: | - -## Reporting a Vulnerability - -Please report vulnerabilities to the authors, either via email or the ESGF Slack. diff --git a/SECURITY.rst b/SECURITY.rst new file mode 100644 index 0000000..71bdbea --- /dev/null +++ b/SECURITY.rst @@ -0,0 +1,22 @@ +Security Policy +=============== + +Supported Versions +------------------ + +No version is currently supported as this package is for +experimentation. + +.. list-table:: Supported Versions + :widths: 25 50 + :header-rows: 1 + + * - Version + - Supported + * - 0.3.1 + - In development + * - 0.3.0 + - Accepting bug reports + +Please report vulnerabilities to the authors, either via email or the +ESGF Slack. \ No newline at end of file diff --git a/docs/code_of_conduct.rst b/docs/code_of_conduct.rst new file mode 100644 index 0000000..910a728 --- /dev/null +++ b/docs/code_of_conduct.rst @@ -0,0 +1 @@ +.. include:: ../CODE_OF_CONDUCT.rst \ No newline at end of file diff --git a/docs/contributing.rst b/docs/contributing.rst new file mode 100644 index 0000000..3bdd7dc --- /dev/null +++ b/docs/contributing.rst @@ -0,0 +1 @@ +.. include:: ../CONTRIBUTING.rst \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index 9e3a1fd..c8762ee 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -6,12 +6,14 @@ ESGF Playground Utils documentation =================================== -Add your content using ``reStructuredText`` syntax. See the -`reStructuredText `_ -documentation for details. - +.. include:: ../README.rst .. toctree:: - :maxdepth: 2 + :maxdepth: 1 :caption: Contents: + security + contributing + code_of_conduct + license + diff --git a/docs/license.rst b/docs/license.rst new file mode 100644 index 0000000..e43b918 --- /dev/null +++ b/docs/license.rst @@ -0,0 +1,4 @@ +License +======= + +.. include:: ../license \ No newline at end of file diff --git a/docs/security.rst b/docs/security.rst new file mode 100644 index 0000000..56ba82d --- /dev/null +++ b/docs/security.rst @@ -0,0 +1 @@ +.. include:: ../SECURITY.rst \ No newline at end of file