sphinx-doc / sphinx-doc/sphinx

sphinx.testing is undocumented

Open
#7,008 19 comments 5 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

type:bug type:docs
Dominant language
Python
Stars
8k
Forks
2.6k
PR merge metrics
No merged PRs in 30d

Description

https://github.com/sphinx-doc/sphinx-testing is marked deprecated and points to sphinx.testing as a replacement. However, the only documentation for this is https://www.sphinx-doc.org/en/master/devguide.html#unit-testing, which does not provide any details.

My first assumption was that maybe it's sufficient to replace from sphinx_testing import with_app with from sphinx.testing import with_app, but that does not seem to be the case:

ImportError: cannot import name 'with_app' from 'sphinx.testing'

I can sort of figure out the use of sphinx.testing by looking at the source code for Sphinx' own tests, but nonetheless there should be proper documentation. The (closed) issue #3458 already pointed out that documentation is still a todo item.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the devguide unit-testing page and inspect the Sphinx project's own test sources to understand the sphinx.testing API and its documented entry points. Document the replacement for sphinx-testing, including the supported usage and the limitations demonstrated by the failed with_app import, so users can follow the documentation without reading the source.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.