Contributing

The following provides a guide for developers wishing to contribute to Sphinx-Needs.

Bugs, Features and PRs

For bug reports and technical well described feature requests please use our issue tracker:

https://github.com/useblocks/sphinxcontrib-needs/issues

For feature ideas and questions please use our discussion board:

https://github.com/useblocks/sphinxcontrib-needs/discussions

If you have already created a PR, awesome! Just send it in. It will be checked by our CI (test and code styles) and a maintainer needs to perform a review, before it can be merged. Your PR should contain the following parts:

• A meaningful description or link, which describes the change

• The changed code (for sure :) )

• 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-Needs 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.

1. Install Poetry

2. Install project dependencies

   poetry install
   

3. Install Pre-Commit

4. Install the Pre-Commit hooks

   pre-commit install
   

5. For running tests install also the dependencies of our official documentation: pip install -r docs/requirements.txt

List make targets

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

Use make list to get a list of available targets.

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

Build docs

This will build the Sphinx-Needs documentation stored under /docs.

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).

make docs-html

or:

make docs-pdf

Check links in docs

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

make docs-linkcheck

Running Tests

Hint

Please be sure to have the dependencies of the official documentation installed: pip install -r docs/requirements.txt

make test

Linting & Formatting

Sphinx-Needs uses black and isort to care about its source code formatting.

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

1. Install Nox

2. Install Nox-Poetry

3. 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

import nox
from nox_poetry import session

PYTHON_VERSIONS = ["3.6", "3.8", "3.9.7"]
SPHINX_VERSIONS = ["3.2", "3.5.4", "4.1", "4.2"]
TEST_DEPENDENCIES = ["nose", "sphinx_testing", "responses", "lxml", "pyparsing!=3.0.4", "requests-mock"]


def is_supported(python: str, sphinx: str) -> bool:
    return not (python == "3.6" and sphinx not in ["3.2"])


def run_tests(session, sphinx):
    session.install(".")
    session.install(*TEST_DEPENDENCIES)
    session.run("pip", "install", f"sphinx=={sphinx}", silent=True)
    session.run("pip", "install", "-r", "docs/requirements.txt", silent=True)
    session.run("echo", "TEST FINAL PACKAGE LIST")
    session.run("pip", "freeze")
    session.run("make", "test", external=True)


@session(python=PYTHON_VERSIONS)
@nox.parametrize("sphinx", SPHINX_VERSIONS)
def tests(session, sphinx):
    if is_supported(session.python, sphinx):
        run_tests(session, sphinx)
    else:
        session.skip("unsupported combination")


@session(python="3.9")
def linkcheck(session):
    session.install(".")
    # LinkCheck cn handle rate limits since Sphinx 3.4, which is needed as
    # our doc has to many links to github.
    session.run("pip", "install", "sphinx==3.5.4", silent=True)

    session.run("pip", "install", "-r", "docs/requirements.txt", silent=True)
    session.run("make", "docs-linkcheck", external=True)

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

Daniel Woste <daniel@useblocks.com>

Contributors

Marco Heinemann <marco@useblocks.com>

Trevor Lovett <trevor.lovett@gmail.com>

Magnus Lööf <magnus.loof@gmail.com>

Harri Kaimio

Anders Thuné

Daniel Eades <danieleades@hotmail.com>

Philip Partsch <philip.partsch@googlemail.com>

David Le Nir <david.lenir.e@thalesdigital.io>

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 most follow [0-9].[0-9]+.[0-9]. Otherwise the release jobs get not triggerd. So other tags can still be used.

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