Contributing¶
This page provides a guide for developers wishing to contribute to Sphinx-Needs.
Bugs, Features and PRs¶
For bug reports and well-described technical feature requests, please use our issue tracker:
https://github.com/useblocks/sphinx-needs/issues
For feature ideas and questions, please use our discussion board:
https://github.com/useblocks/sphinx-needs/discussions
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 with the following rules:
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.
Install project dependencies
poetry install
Install the Pre-Commit hooks
pre-commit install
For running tests, install 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.
benchmark-memory
benchmark-time
docs-html
docs-html-fast
docs-linkcheck
docs-pdf
format
lint
test
test-matrix
test-short
Build docs¶
To build the Sphinx-Needs 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¶
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 format its source code.
make lint
Benchmarks¶
Sphinx-Needs own documentation is used for creating a benchmark for each PR. If the runtime takes 10% longer as the previous ones, the benchmark test will fail.
Benchmark test cases are available under tests/benchmarks
.
And they can be locally executed via make benchmark
.
The results for each PR/commit get added to a chart, which is available under http://useblocks.com/sphinx-needs/bench/index.html.
The benchmark data is stored on the benchmarks branch, which is also used by github-pages as source.
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
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
# The versions here must be in sync with the github-workflows.
# Or at least support all version from there.
# This list can contain more versions as used by the github workflows to support
# custom local tests
PYTHON_VERSIONS = ["3.8", "3.10"]
SPHINX_VERSIONS = ["5.2.1", "4.5.0"]
DOCUTILS_VERSIONS = ["0.19", "0.17", "0.16", "0.15"]
TEST_DEPENDENCIES = [
"pytest",
"pytest-xdist",
"responses",
"lxml",
"pyparsing!=3.0.4",
"requests-mock",
]
# Some pytest-extension do not work well with pytest-benchmark, so we create our
# own list for benchmarking
BENCHMARK_DEPENDENCIES = [e for e in TEST_DEPENDENCIES if e not in ['"pytest-xdist"']]
BENCHMARK_DEPENDENCIES.append("py")
BENCHMARK_DEPENDENCIES.append("memray")
BENCHMARK_DEPENDENCIES.append("pytest-benchmark")
def is_supported(python: str, sphinx: str, docutils: str) -> bool:
return not (sphinx in ["4.5.0"] and docutils in ["0.19", "0.18"])
def run_tests(session, sphinx, docutils):
session.install(".")
session.install(*TEST_DEPENDENCIES)
session.run("pip", "install", "-r", "docs/requirements.txt", silent=True)
session.run("pip", "install", f"sphinx=={sphinx}", silent=True)
session.run("pip", "install", f"docutils=={docutils}", 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("docutils", DOCUTILS_VERSIONS) # order is important, last options needs to be given first ...
@nox.parametrize("sphinx", SPHINX_VERSIONS) # ... by GH workflow
def tests(session, sphinx, docutils):
if is_supported(session.python, sphinx, docutils):
run_tests(session, sphinx, docutils)
else:
session.skip("unsupported combination")
@session(python="3.10")
def linkcheck(session):
session.install(".")
# LinkCheck can handle rate limits since Sphinx 3.4, which is needed as
# our doc has too 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)
@session(python="3.10")
def benchmark_time(session):
session.install(".")
session.install(*BENCHMARK_DEPENDENCIES)
session.run("pip", "install", "-r", "docs/requirements.txt", silent=True)
session.run(
"pytest",
"tests/benchmarks",
"-k",
"_time",
"--benchmark-json",
"output.json",
external=True,
env={"ON_CI": "true", "FAST_BUILD": "true"},
)
@session(python="3.10")
def benchmark_memory(session):
session.install(".")
session.install(*BENCHMARK_DEPENDENCIES)
session.run("pip", "install", "-r", "docs/requirements.txt", silent=True)
session.run(
"pytest",
"tests/benchmarks",
"-k",
"_memory",
"--benchmark-json",
"output.json",
external=True,
env={"ON_CI": "true", "FAST_BUILD": "true"},
)
session.run("memray", "flamegraph", "-o", "mem_out.html", "mem_out.bin")
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>
).
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
.
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>
Baran Barış Yıldızlı <arisbbyil@gmail.com>
Roberto Rötting <roberto.roetting@gmail.com>
Nirmal Sasidharan <nirmal.sasidharan@de.bosch.com>
Jacob Allen <jacob.allen@etas.com>
Jörg Kreuzberger <j.kreuzberger@procitec.de>
Duodu Randy <duodurandy19@gmail.com>
Christian Wappler <chri.wapp@gmail.com>