Move back to sphinx for documentation? #952
Description
Last mid last year a pull request was merged that started a new documentation using MkDocs instead of Sphinx.
I already commented on the MR, which is probably not the right place for a broader discussion, so I am raising this here as a dedicated issue.
Summary
I want to start by saying that I value the new documentation content itself and would like to keep that content. My concerns are mainly about the documentation system and structure, not the substance.
The switch from Sphinx to MkDocs is a notable change to the project’s documentation tooling, and I would like to better understand the motivation and trade-offs behind this decision.
Tooling concerns
Loss of Sphinx features
With Sphinx, the project previously benefited from features that are particularly relevant for Python users:
- Autodoc / AutoAPI, keeping documentation close to the code.
- Doctests, ensuring that examples are executed and remain correct.
- Intersphinx inventories, allowing other projects to link directly to API documentation.
The importance of doctests is not theoretical. While working on an unrelated PR, I noticed that the Cassandra example currently fails with:
AttributeError: 'CassandraContainer' object has no attribute 'port'. Did you mean: 'ports'?This is exactly the type of issue doctests would catch automatically.
If Markdown is a requirement, Sphinx already supports it well via MyST, so MkDocs is not the only option.
requirements.txt
As part of the new setup, a requirements.txt file was added at the project root, not within the docs/ folder where such a file would conventionally belong.
- Its presence at the project root is confusing in the context of a modern Python project using
pyproject.toml. - Declaring documentation dependencies this way feels outdated.
- There are documented alternatives that avoid this pattern, including:
Both approaches support lock files and integrate cleanly with current Python packaging practices.
The combination of broken examples and the dependency setup gives the impression that parts of the documentation were LLM-generated and not subsequently reviewed by contributors actively working with current Python tooling.
Documentation site design / theming
It is unclear how strongly this project needs to align its documentation site design and theming with the “official” Testcontainers website.
Sphinx offers sufficient theming flexibility to achieve a similar look if desired, and other Testcontainers implementations (e.g. Rust) use different approaches altogether. This raises the question of how much visual alignment should influence tooling decisions.
Possible next steps
To summarize my intent:
- I would like to keep the new documentation content.
- I am not convinced that MkDocs provides enough benefits here to offset the loss of Sphinx features.
- The current dependency handling is confusing and has well-documented alternatives.
If there is interest from the maintainers, I would consider helping with or taking on the task of moving the new documentation content back to a Sphinx-based setup, possibly with some adjustments (e.g. reworking examples to restore doctest coverage).
Before investing time into this, it would be good to know whether such a direction would be welcome.