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@e7feb53). 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.