diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000..9bea9f6 --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,24 @@ +# .readthedocs.yaml +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +# Required +version: 2 + +formats: + - epub + - pdf + +# Set the version of Python and other tools you might need +build: + os: ubuntu-22.04 + tools: + python: "3.9" + +mkdocs: + configuration: mkdocs.yml + +# Optionally declare the Python requirements required to build your docs +python: + install: + - requirements: docs/requirements.txt diff --git a/CONTRIBUTE.md b/CONTRIBUTE.md new file mode 100644 index 0000000..f864b1f --- /dev/null +++ b/CONTRIBUTE.md @@ -0,0 +1,72 @@ +# Contribute to momoa + +## Development Environment + +[Poetry](https://python-poetry.org) is used for dependency and package management. The steps for setting up the development environment: + +1. Install Poetry: either [globally](https://python-poetry.org/docs/#installation), or in a Python virtual environment (using `pip install poetry`). + +3. Install the project (if outside a virtual environment, Poetry will create one): + + $ poetry install + + +### Code Validation + +[tox](https://tox.wiki) is being used to execute multiple code validation checks at once: + +```shell +$ tox +``` + +This command will automatically run a number of code validation checks, as well as the unit test suite for multiple versions of Python. + +**Note:** For local development, use `pyenv` to install multiple versions of Python and set them up as local in the root directory of the project; for example: + +```shell +$ pyenv install 3.8.13 +$ pyenv install 3.9.12 +$ pyenv install 3.10.4 +$ pyenv local 3.8.13 3.9.12 3.10.4 +``` +This is not needed for the CI, which runs one one Python version (image) at a time. + +#### Manual Validation + +During development, each code check can be executed independently: + +```shell +$ flake8 # code linting +$ mypy --install-types --non-interactive momoa/ # Python typing analysis +$ black --check . # Python code formatting +$ isort --check . # Import statement optimisation +$ pydocstyle momoa/ # styling and completeness of docstrings +``` + +For unit tests use: + +```shell +$ pytest --cov --spec +``` + +The indicated options add extra details to the report: + +* `--cov` adds a test coverage report +* `--spec` formats the test report as a list of spec statements + + +## API Documentation + +The project documentation can be served locally by running: + +```shell +$ python -m mkdocs serve +``` + +To build the static documentation site, run: + +```shell +$ python -m mkdocs build +``` + +This will create the HTML documentation in the `site` directory. diff --git a/README.md b/README.md index 1b77542..478d115 100644 --- a/README.md +++ b/README.md @@ -2,73 +2,3 @@ A library for definition, validation and serialisation of models based on JSONSchema specifications. -## Development Environment - -[Poetry](https://python-poetry.org) is used for dependency and package management. The steps for setting up the development environment: - -1. Install Poetry: either [globally](https://python-poetry.org/docs/#installation), or in a Python virtual environment (using `pip install poetry`). - -3. Install the project (if outside a virtual environment, Poetry will create one): - - $ poetry install - - -### Code Validation - -[tox](https://tox.wiki) is being used to execute multiple code validation checks at once: - -```shell -$ tox -``` - -This command will automatically run a number of code validation checks, as well as the unit test suite for multiple versions of Python. - -**Note:** For local development, use `pyenv` to install multiple versions of Python and set them up as local in the root directory of the project; for example: - -```shell -$ pyenv install 3.8.13 -$ pyenv install 3.9.12 -$ pyenv install 3.10.4 -$ pyenv local 3.8.13 3.9.12 3.10.4 -``` -This is not needed for the CI, which runs one one Python version (image) at a time. - -#### Manual Validation - -During development, each code check can be executed independently: - -```shell -$ flake8 # code linting -$ mypy --install-types --non-interactive momoa/ # Python typing analysis -$ black --check . # Python code formatting -$ isort --check . # Import statement optimisation -$ pydocstyle momoa/ # styling and completeness of docstrings -``` - -For unit tests use: - -```shell -$ pytest --cov --spec -``` - -The indicated options add extra details to the report: - -* `--cov` adds a test coverage report -* `--spec` formats the test report as a list of spec statements - - -## API Documentation - -The project documentation can be served locally by running: - -```shell -$ python -m mkdocs serve -``` - -To build the static documentation site, run: - -```shell -$ python -m mkdocs build -``` - -This will create the HTML documentation in the `site` directory. diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..4ce33f8 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,2 @@ +mkdocs>=1.2.3 +mkapi>=1.0.14 diff --git a/mkdocs.yml b/mkdocs.yml index b4f4c84..6522217 100755 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,5 +1,5 @@ site_name: Momoa -repo_url: +repo_url: https://github.com/berislavlopac/momoa site_description: A library for definition, validation and serialisation of models based on JSONSchema specifications. site_author: Berislav Lopac use_directory_urls: false @@ -10,11 +10,6 @@ extra_css: plugins: - search - mkapi -markdown_extensions: - - toc: - permalink: yes - - codehilite: - guess_lang: no nav: - index.md - reference.md diff --git a/pyproject.toml b/pyproject.toml index 98d8620..e8c5627 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -14,7 +14,7 @@ statham-schema = "^0.13.5" stringcase = "^1.2.0" python-dateutil = "^2.8.2" -[tool.poetry.dev-dependencies] +[tool.poetry.group.dev.dependencies] pytest = ">=7.1.2" pytest-cov = ">=3.0.0" black = ">=22.1.0"