Contributing

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

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 – Sphinx-CodeLinks is developed in the useblocks/sphinx-needs monorepo, under packages/sphinx-codelinks/. Pick sphinx-codelinks from the issue form’s Package dropdown.

If you have already created a PR, you can send it in. Our CI workflow will check (tests 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.

Pull requests are written by people. A pull request that was generated automatically from an issue – opened by an account that has not read the code, run the tests or taken part in the discussion, typically within hours of the issue being filed – is closed without review, whatever its content. We cannot tell a good one from a bad one without the full review a change of our own would get, and its author knows nothing of the tools this repository serves or of where the change sits in our plans. Using an AI assistant for your own work is fine: you have read the change, you have tested it, and you answer for it. Say so in the pull request template.

Install Dependencies

Development tasks are uv and poethepoet tasks, run from the repository root. One sync installs every package in the workspace and the shared test tooling:

uv sync --frozen

Formatting, Linting and Typing

Formatting and linting are one hook set over the whole repository:

uv run poe lint

Type checking runs ty against the oldest supported Sphinx:

uv run poe typecheck

Build docs

To build the documentation stored in packages/sphinx-codelinks/docs, run:

uv run poe docs-codelinks         # or docs-codelinks-clean to rebuild from scratch

Test Cases

To run test cases locally:

uv run poe test-codelinks

The task adds the codelinks-libclang dependency group, which is where the optional preprocessor-aware C/C++ engine comes from – without it 56 tests skip rather than run. test-codelinks-sphinx7, -sphinx8 and -sphinx9 run one matrix cell each.

Note some tests use syrupy to perform snapshot testing. These snapshots can be updated by running:

uv run poe test-codelinks -- --snapshot-update