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
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.
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
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.8", "3.9.7", "3.10"]
SPHINX_VERSIONS = ["4.0.3", "4.3.2", "4.5"]
TEST_DEPENDENCIES = [
"pytest",
"pytest-xdist",
"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 can 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>
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>
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 triggered.
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
.
Debugging Sphinx-Needs Language Server features¶
Sphinx-Needs provides some language server functions for the Esbonio Language Server.
The complete functionality can used in VsCode by using the extension vscode-restructuredtext. The whole configuration is done automatically and Sphinx-Needs features gets loaded, if the Sphinx-Needs extension is part of ´extensions` variable inside conf.py.
Debugging¶
Most information is coming from https://docs.restructuredtext.net/articles/development.html.
Check out the source code of all the following projects:
vscode-restructuredtext: links…
esbonio
Follow https://docs.restructuredtext.net/articles/development.html to install all dependencies, compile it and get the Development host running in VsCode.
Create a test folder inside the project with a Sphinx projects using Sphinx-Needs, for example under /docs by using sphinx-quickstart.
Add the following to docs/.vscode/settings.json:
{ "esbonio.server.sourceFolder": "/Path/to/checked_out/esbonio/lib/esbonio", # absolute path "esbonio.server.debugLaunch": true, "esbonio.server.logLevel": "debug", }
Add the args ${workspaceFolder}/docs to configuration Launch Extension in .vscode/launch.json like this:
{ "name": "Launch Extension", "type": "extensionHost", "request": "launch", "runtimeExecutable": "${execPath}", "args": [ "--extensionDevelopmentPath=${workspaceRoot}", "${workspaceFolder}/docs", ], "sourceMaps": true, "outFiles": ["${workspaceRoot}/out/extension.js"], "preLaunchTask": "watch" },
Test it by pressing F5 (running the preconfigured tasks Launch Extension)
In the opened extensionDevelopmentHost instance, select the correct python interpretor. e.g. vscode-restructuredtext/.venv/bin/python
Open another instance of VsCode for the checked out esbonio folder.
Add this to .vscode/launch.json under configurations:
{ "name": "Python: Remote Attach", "type": "python", "request": "attach", "connect": { "host": "localhost", "port": 5678 }, "pathMappings": [ { "localRoot": "${workspaceFolder}/lib/esbonio", "remoteRoot": "." } ] },
Test it by running the new task Python: Remote Attach. For this the task Launch Extension from VsCode-restructuredText Extension must be already running, as this one starts a python debug server.
Now you set set breakpoints anywhere in the esbonio code.
Debugging Sphinx-Needs functions¶
To debugging Sphinx-Needs Language Server functions, you can repeat the steps 7-10 from above with the Sphinx-Needs repository.
Note:
For step 8: adapt the localRoot path accordingly, e.g. “${workspaceFolder}/../esbonio/lib/esbonio”
If it doesn’t stop at breakpoints, set a breakpoint at sphinx_needs/__init__.py, where you import esbonio_setup. When debugger stops there, choose step into to continue debug.