From 92d1ebd3442f9c913c854338609a5739f64d77fe Mon Sep 17 00:00:00 2001 From: Marcos Pereira Jr Date: Thu, 15 Feb 2024 00:36:12 -0300 Subject: [PATCH] feat: new docs. --- docs/source/api.rst | 9 +++ docs/source/changelog.rst | 5 ++ docs/source/contributing.rst | 104 ++++++++++++++++++++++++++++++++ docs/source/getting_started.rst | 4 ++ docs/source/index.rst | 22 +++++-- docs/source/install.rst | 47 +++++++++++++++ 6 files changed, 187 insertions(+), 4 deletions(-) create mode 100644 docs/source/contributing.rst create mode 100644 docs/source/getting_started.rst create mode 100644 docs/source/install.rst diff --git a/docs/source/api.rst b/docs/source/api.rst index e69de29..991cd04 100644 --- a/docs/source/api.rst +++ b/docs/source/api.rst @@ -0,0 +1,9 @@ +.. _api: + +The API Documentation +======================== + +.. toctree:: + :maxdepth: 2 + + reference/keycloak/index diff --git a/docs/source/changelog.rst b/docs/source/changelog.rst index ab37940..dedf70b 100644 --- a/docs/source/changelog.rst +++ b/docs/source/changelog.rst @@ -1 +1,6 @@ +.. _changelog: + +Changelog +======================== + .. mdinclude:: ../../CHANGELOG.md diff --git a/docs/source/contributing.rst b/docs/source/contributing.rst new file mode 100644 index 0000000..801de92 --- /dev/null +++ b/docs/source/contributing.rst @@ -0,0 +1,104 @@ +.. _contributing: + +The Contributor Guide +======================== + +Welcome to the Python Keycloak contributing guidelines. We are all more than happy to receive +any contributions to the repository and want to thank you in advance for your contributions! +This document outlines the process and the guidelines on how contributions work for this repository. + +Setting up the dev environment +------------------------------- + +The development environment is mainly up to the developer. Our recommendations are to create a python +virtual environment and install the necessary requirements. Example + +.. code-block:: console + + # Install and upgrade pip & poetry + python -m pip install --upgrade pip poetry + + # Create virtualenv + python -m poetry env use + + # install package dependencies including dev dependencies + python -m poetry install + + # Activate virtualenv + python -m poetry shell + +Running checks and tests +--------------------------- + +We're utilizing `tox` for most of the testing workflows. However we also have an external dependency on `docker`. +We're using docker to spin up a local keycloak instance which we run our test cases against. This is to avoid +a lot of unnecessary mocking and yet have immediate feedback from the actual Keycloak instance. All of the setup +is done for you with the tox environments, all you need is to have both tox and docker installed +(`tox` is included in the `dev-requirements.txt`). + +To run the unit tests, simply run + +.. code-block:: console + + tox -e tests + +The project is also adhering to strict linting (flake8) and formatting (black + isort). You can always check that +your code changes adhere to the format by running + +.. code-block:: console + + tox -e check + +If the check fails, you'll see an error message specifying what went wrong. To simplify things, you can also run + +.. code-block:: console + + tox -e apply-check + +which will apply isort and black formatting for you in the repository. The flake8 problems however need to be resolved +manually by the developer. + +Additionally we require that the documentation pages are built without warnings. This check is also run via tox, using +the command + +.. code-block:: console + + tox -e docs + + +The check is also run in the CICD pipelines. We require that the documentation pages built from the code docstrings +do not create visually "bad" pages. + +Conventional commits +---------------------- + +Commits to this project must adhere to the [Conventional Commits +specification](https://www.conventionalcommits.org/en/v1.0.0/) that will allow +us to automate version bumps and changelog entry creation. + +After cloning this repository, you must install the pre-commit hook for +conventional commits (this is included in the `dev-requirements.txt`) + +.. code-block:: console + + # Create virtualenv + python -m poetry env use + + # Activate virtualenv + python -m poetry shell + + pre-commit install --install-hooks -t pre-commit -t pre-push -t commit-msg + +How to contribute +------------------- + +1. Fork this repository, develop and test your changes +2. Make sure that your changes do not decrease the test coverage +3. Make sure you're commits follow the conventional commits +4. Submit a pull request + +How to release +------------------- + +The CICD pipelines are set up for the repository. When a PR is merged, a new version of the library +will be automatically deployed to the PyPi server, meaning you'll be able to see your changes immediately. diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst new file mode 100644 index 0000000..b958b9a --- /dev/null +++ b/docs/source/getting_started.rst @@ -0,0 +1,4 @@ +.. _getting_started: + +The User Guide +======================== diff --git a/docs/source/index.rst b/docs/source/index.rst index ecf88ea..230c058 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -3,13 +3,27 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. +Python-Keycloak +======================== + +.. image:: https://github.com/marcospereirampj/python-keycloak/actions/workflows/daily.yaml/badge.svg + :target: https://github.com/marcospereirampj/python-keycloak/actions/workflows/daily.yaml/badge.svg .. image:: https://readthedocs.org/projects/adamatics-keycloak/badge/?version=latest :target: https://adamatics-keycloak.readthedocs.io/en/latest/?badge=latest -.. mdinclude:: ../../README.md + +**python-keycloak** is a Python package providing access to the Keycloak API. + +------------------- + +Useful Links +---------------- + .. toctree:: :maxdepth: 2 - :caption: Contents: + :caption: Contents - readme + getting_started + install + api + contributing changelog - reference/keycloak/index diff --git a/docs/source/install.rst b/docs/source/install.rst new file mode 100644 index 0000000..a53a003 --- /dev/null +++ b/docs/source/install.rst @@ -0,0 +1,47 @@ +.. _install: + +Installation +======================== + +This part of the documentation covers the installation of Python-Keycloak. This is the first step to using the software library. + +Via Pypi Package +----------------- + +To install python-keycloak, run this command in your terminal of choice:: + + pip install python-keycloak + +Manually +----------------- + +The python-keycloak code is `available `_. on Github. + +You can either clone the public repository:: + + git clone https://github.com/marcospereirampj/python-keycloak.git + +Or, download the source code. + +Once you have a copy of the source, you can embed it in your own Python package, or install it into your site-packages easily:: + + python -m pip install . + +Dependencies +----------------- + +python-keycloak depends on: + +- Python 3 +- [requests](https://requests.readthedocs.io) +- [python-jose](http://python-jose.readthedocs.io/en/latest/) +- [urllib3](https://urllib3.readthedocs.io/en/stable/) + + +Tests Dependencies +----------------- + +- [tox](https://tox.readthedocs.io/) +- [pytest](https://docs.pytest.org/en/latest/) +- [pytest-cov](https://github.com/pytest-dev/pytest-cov) +- [wheel](https://github.com/pypa/wheel)