Contributing¶
The following provides a guide for developers wishing to contribute
to Sphinx-Needs.
Bugs, Features and PRs¶
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
AUTHORSfile.
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
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-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¶
make test
Linting¶
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
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.7", "3.8", "3.9"]
SPHINX_VERSIONS = ["3.2", "3.3", "3.4", "3.5"]
TEST_DEPENDENCIES = [
"nose",
"sphinx_testing",
"responses",
]
LINT_DEPENDENCIES = [
"flake8",
"pep8-naming",
"flake8-isort",
"flake8-black",
]
def is_supported(python: str, sphinx: str) -> bool:
return not (python == "3.6" and float(sphinx) > 3.0)
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("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 lint(session):
session.install(*LINT_DEPENDENCIES)
session.run("make", "lint", external=True)
@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)
Formatting¶
Sphinx-Needs uses black and
isort to care about its source code formatting.
To run both:
make format
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>
