Contributing¶

This page provides a guide for developers wishing to contribute to Sphinx-EMF.

Bugs, Features and PRs¶

For bug reports and well-described technical feature requests, please use our issue tracker:
https://github.com/useblocks/sphinx-emf/issues

If you have already created a PR, you can send it in. Our CI workflow will check (test and code styles) and a maintainer will perform a review, before we can merge it. Your PR should conform to the following rules:

A meaningful description or link, which describes the change
Test cases for the change (important!)
Updated documentation, if behavior gets changed or new options/directives are introduced.
Update of docs/changelog.rst.
If this is your first PR, feel free to add your name in the AUTHORS file.

Installing Dependencies¶

Sphinx-EMF requires only Poetry to be installed as a system dependency, the rest of the dependencies are ‘bootstrapped’ and installed in an isolated environment by Poetry.

Install Poetry
Install project dependencies
```
poetry install
```
Install Pre-Commit
Install the Pre-Commit hooks
```
pre-commit install
```

List make targets¶

Sphinx-EMF uses make to invoke most development related actions.

Use make list to get a list of available targets.

docs-html
docs-html-fast
docs-pdf
format
lint
test
test-matrix
test-short

Build docs¶

To build the Sphinx-EMF documentation stored under /docs, run:

# Build HTML pages
make docs-html

or

# Build PDF pages
make docs-pdf

It will always perform a clean build (calls make clean before the build). If you want to avoid this, run the related sphinx-commands directly under /docs (e.g. make docs).

Check links in docs¶

To check if all used links in the documentation are still valid, run:

make docs-linkcheck

Running Tests¶

make test

Linting & Formatting¶

Sphinx-EMF uses black and isort to format its source code.

make lint

Running Test Matrix¶

This project provides a test matrix for running the tests across a range of Python and Sphinx versions. This is used primarily for continuous integration.

Nox is used as a test runner.

Running the matrix tests requires additional system-wide dependencies

Install Nox
Install Nox-Poetry
You will also need multiple Python versions available. You can manage these using Pyenv

You can run the test matrix by using the nox command

nox

or using the provided Makefile

make test-matrix

For a full list of available options, refer to the Nox documentation, and the local noxfile.

Our noxfile.py

"""
Configuration file for nox.

May define a matrix build for dependency combinations.
"""

from nox_poetry import session


PYTHON_VERSIONS = ["3.7", "3.8", "3.9", "3.10"]
# DEP_VERSIONS = ["5.0.2"]


def run_tests(local_session) -> None:
    """Install the dependencies for the matrix build library versions and run the tests."""
    local_session.install(".")
    # session.run("pip", "install", f"lib=={lib_version}")
    # session.run("echo", "FINAL PACKAGE LIST", external=True)
    # session.run("pip", "freeze")
    local_session.run(
        "make", "test", external=True
    )  # runs 'poetry run pytest' which re-uses the active nox environment


@session(python=PYTHON_VERSIONS, reuse_venv=True)  # noqa: F841
# @nox.parametrize("lib_dependency", DEP_VERSIONS)  # add lib_dependency to the function params to enable matrix build
def tests(session):  # pylint: disable=redefined-outer-name
    """Run the nox matrix build test cases."""
    run_tests(session)

Running Commands¶

See the Poetry documentation for a list of commands.

In order to run custom commands inside the isolated environment, they should be prefixed with poetry run (ie. poetry run <command>).

Maintainers¶

Marco Heinemann <marco.heinemann@useblocks.com>

Contributors¶

Publishing a new release¶

There is a release pipeline installed for the CI.

This gets triggered automatically, if a tag is created and pushed. The tag must follow the format: [0-9].[0-9]+.[0-9]. Otherwise the release jobs won’t trigger.

The release jobs will build the source and wheel distribution and try to upload them to test.pypi.org and pypy.org.