Marcos Pereira Jr
9 months ago
committed by
Marcos Pereira
6 changed files with 187 additions and 4 deletions
-
9docs/source/api.rst
-
5docs/source/changelog.rst
-
104docs/source/contributing.rst
-
4docs/source/getting_started.rst
-
22docs/source/index.rst
-
47docs/source/install.rst
@ -0,0 +1,9 @@ |
|||
.. _api: |
|||
|
|||
The API Documentation |
|||
======================== |
|||
|
|||
.. toctree:: |
|||
:maxdepth: 2 |
|||
|
|||
reference/keycloak/index |
@ -1 +1,6 @@ |
|||
.. _changelog: |
|||
|
|||
Changelog |
|||
======================== |
|||
|
|||
.. mdinclude:: ../../CHANGELOG.md |
@ -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 <PATH_TO_PYTHON_VERSION> |
|||
|
|||
# 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 <PATH_TO_PYTHON_VERSION> |
|||
|
|||
# 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. |
@ -0,0 +1,4 @@ |
|||
.. _getting_started: |
|||
|
|||
The User Guide |
|||
======================== |
@ -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 <https://github.com/marcospereirampj/python-keycloak>`_. 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) |
Write
Preview
Loading…
Cancel
Save
Reference in new issue