feat(main): New Testcontainers Python Docs Site

[terry-docker]

Hello all!

I've been working on getting a new and improved docs site for Testcontainers Python. This docs site aligns it with Testcontainers Java/Go/.NET/Node which will hopefully help users onboard and adopt Testcontainers more easily.

Testing fork deploys can be seen here, I'm also lining up the official builds to live on the python.testcontainers.org name space! 👀
https://exquisite-dusk-036c28.netlify.app/

Why?

We (Docker) want to support the Python community! A big improvement opportunity I saw was the current docs site compared to some of the other languages. Adopting the same template and builds will help keep use inline with the other and hopefully make Testcontainers Python easier to adopt by providing a starting point with more guide style content.

Usage and Details

The old Sphinx site has been left untouched for now (TBD by the community if it's provided value imo). This is a large change for writing documentation on the lib. There is now a /docs folder filler with markdown files rather then being powered only by code comments. The left hand navigation is controlled by a new yml file on the root of the project called mkdocs.yml.

Rather then using Sphinx to parse code comments, with mkdocs you can include example python files to go with the documentation. I've created community module usage examples beside their implementation called example_basic.py but people can make other example files in the source as well. The linter is ignoring files with example_ in them to ease builds for the docs purposes (and missing dependencies that may not matter).

In the documentation site you can them import your examples via

# MinIO

........

## Usage example

<!--codeinclude-->

[Creating a MinIO container](../../modules/minio/example_basic.py)

<!--/codeinclude-->

Content was largely generated by reading the source code with an editing pass from one of Docker's technical writers.

Running / Editing the Docs Site Locally

A new Testcontainer python docs Dockerfile lives in the root of the project which handles the docssite specific dependencies. The container will build and serve the site for you.

make serve-docs

How Documentation Will Deploy

It's Netlify powered. We can configure it to do preview deploys per PR and deploy a new site on merge to main. Unfortunately Netlify doesn't support Poetry so to keep the builds simple there is a requirements.txt for explicitly the docs site dependency.

The Contents of the New Documentation

As mentioned briefly in the opening we used AI to help generate the content of the site by reading the source code, myself and Arthur also did some human passes to ensure things read well, but clearly more help from people ensuring the accuracy will come over time. Once the new docs site is merged into main and hosting is fully working I think we should post in the community slack and ask for feedback, the two docs sites will run concurrently before officially launching (replacing) the current docs site.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Please upload report for BASE (main@632e5f4). Learn more about missing BASE report.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #822   +/-   ##
=======================================
  Coverage        ?   85.46%           
=======================================
  Files           ?       12           
  Lines           ?      688           
  Branches        ?      110           
=======================================
  Hits            ?      588           
  Misses          ?       75           
  Partials        ?       25           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[terry-docker]

Converting to draft to address community module test issues and the diff has some changes branched off of #814 so I could verify everything was running locally.

[CarliJoy]

I find it unfortunate that this MR was merged without prior discussion.

In my view, switching the project’s documentation system from Sphinx to MkDocs is a significant architectural change that warrants broader consensus. The current documentation stack is built around Sphinx, including its AutoAPI integration and the use of doctests. The latter is particularly valuable, as it ensures that the examples in the documentation are executable and remain correct over time.

If Markdown is a requirement, Sphinx already provides first-class support via its Markdown parser, so adopting MkDocs is not the only path forward.

Additionally, introducing a requirements.txt file feels outdated. Dependencies should be declared in pyproject.toml, ideally using a dedicated optional dependency group (e.g. docs), which aligns with modern Python packaging practices.

From a Python developer’s perspective, a well-structured Sphinx documentation is both familiar and easier to navigate than a custom, project-specific documentation style. I am not convinced that this change meaningfully improves onboarding for new users, who are likely already accustomed to standard Python documentation tooling.

Just my two cents.

[alexanderankin]

@CarliJoy readthedocs where the docs were hosted does not support anything but requirements.txt, i think the problem is there rather than here

[CarliJoy]

Ah, I see — my mistake.

That said, even considering the examples in the Read the Docs documentation for both Sphinx and MkDocs, the requirements.txt file should live under docs/ rather than in the project root, where it is confusing in the context of a modern Python project.
See: https://docs.readthedocs.com/platform/stable/examples.html

More generally, my original concern still stands: moving to MkDocs introduces several drawbacks with, in my view, limited tangible benefits.

Is there a concrete technical advantage of using MkDocs over Sphinx for this project?

Key features we currently (or previously) benefit from with Sphinx include:

• Autodoc / AutoAPI support, keeping documentation close to the code and avoiding duplication.
• Doctests, ensuring that examples in the documentation are actually executed and remain correct.
• Support for generating intersphinx inventory files, allowing other projects to link directly to AutoDoc-generated API documentation (e.g. references to Container in docstrings automatically linking back to the original documentation).

In addition, Sphinx offers extensive theming capabilities, including several solid default themes and a large ecosystem of community-maintained themes. This makes it entirely feasible to achieve a look and feel similar to the “official” Testcontainers documentation, if that is a goal.

So my question to @alexanderankin is: would you be open to accepting a PR that converts the documentation introduced in this MR back to Sphinx?

Related to that, how important is it for this project that the documentation style aligns with the “official” Testcontainers pages? I notice, for example, that the Rust Testcontainers documentation also uses a custom-looking style.

I am not sure I will personally have the capacity to work on such a conversion in the near future, but it might be something another contributor could pick up — or something I could revisit later. In any case, it would be good to understand upfront whether such a PR would be welcome, as no one wants to invest time into work that is unlikely to be accepted.

[CarliJoy]

Working on a different PR I just saw that given example for casandra does not work and results in

Traceback (most recent call last):
  File "testcontainers-python/modules/cassandra/example_basic.py", line 153, in <module>
    basic_example()
  File "testcontainers-python/modules/cassandra/example_basic.py", line 14, in basic_example
    port = cassandra.get_exposed_port(cassandra.port)
                                      ^^^^^^^^^^^^^^
AttributeError: 'CassandraContainer' object has no attribute 'port'. Did you mean: 'ports'?

Just showing that doctests are important.