What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
To test documentation code on every build, make example checks part of the same automated workflow as the site build. Sphinx has a built-in doctest builder for examples you mark for execution. For MkDocs, a documented third-party option uses pytest to build the site and check its generated pages; verify that it works with your MkDocs version and plugins before adopting it.
Choose what the build should verify
A successful documentation build does not necessarily mean every highlighted code block ran. Choose the examples that should be executable, mark them using the mechanism for your documentation tool, and make their dependencies and expected results clear.
- Use executable examples when you want to check that documented code still runs.
- Check rendered pages as well if you need to verify generated HTML content or structure.
- Consider optional dependencies and supported environments explicitly; a skipped example should not hide a failure in an environment where it is required.
The cited Sphinx and MkDocs-Test documentation describes selected examples and page checks, not automatic execution of every arbitrary highlighted block.
Recommended Free Tools
Run marked examples with Sphinx
Sphinx provides sphinx.ext.doctest. Add it to the extensions list in conf.py:
#1 Best Overall
- Includes Raspberry Pi 5 with 2.4Ghz 64-bit quad-core CPU (8GB RAM)
- Includes 128GB Micro SD Card pre-loaded with 64-bit Raspberry Pi OS, USB MicroSD Card Reader
- CanaKit Turbine Black Case for the Raspberry Pi 5
- CanaKit Low Noise Bearing System Fan
- Mega Heat Sink - Black Anodized
extensions = [
"sphinx.ext.doctest",
]Mark an interactive example with a doctest directive:
.. doctest::
>>> 1 + 1
2Or put code and its expected output in separate directives:
Rank #2
- Includes Raspberry Pi 4 4GB Model B with 1.5GHz 64-bit quad-core CPU (4GB RAM)
- Includes Pre-Loaded 32GB EVO+ Micro SD Card (Class 10), USB MicroSD Card Reader
- CanaKit Premium High-Gloss Raspberry Pi 4 Case with Integrated Fan Mount, CanaKit Low Noise Bearing System Fan
- CanaKit 3.5A USB-C Raspberry Pi 4 Power Supply (US Plug) with Noise Filter, Set of Heat Sinks, Display Cable - 6 foot (Supports up to 4K60p)
- CanaKit USB-C PiSwitch (On/Off Power Switch for Raspberry Pi 4)
.. testcode::
print(1 + 1)
.. testoutput::
2Run the doctest builder in addition to your normal site builder:
sphinx-build -b doctest docs docs/_build/doctestThe extension supports grouping, setup and cleanup, comparison flags, and conditional skips for cases such as optional dependencies. Define what environment each example supports, and use a skip only when the example is genuinely inapplicable—not to suppress a failure that should block the build. See the Sphinx doctest extension documentation for the available directives and behavior.
Check a MkDocs site with pytest
The third-party MkDocs-Test getting-started guide documents a pytest workflow: install MkDocs-Test and pytest, enable test in mkdocs.yml, then write tests that build the site through DocProject and inspect the resulting pages. Its examples check whether the project build succeeds and examine generated HTML content.
This approach can verify rendered output as well as build success, but it is not a built-in MkDocs test builder. The guide does not establish compatibility with every current MkDocs release or every plugin combination. Check the package’s maintenance, supported MkDocs versions, and interactions with your project’s plugins before making it a required check. MkDocs notes that plugins are installed packages whose code runs in the build environment, so review the dependency as you would other build-time code. See the MkDocs-Test getting-started guide and the official MkDocs plugin documentation.
Rank #4
- Broadcom BCM2711, quad-core Cortex-A72 (ARM v8) 64-bit SoC @ 1. 5GHz
- 2. 4 GHz and 5. 0 GHz IEEE 802. 11b/g/n/ac wireless LAN, Bluetooth 5. 0, BLE
- 2 × USB 3. 0 ports, 2 x USB 2. 0 Ports
- 2 × micro HDMI ports supproting up to 4Kp60 video resolution
- Micro SD card slot for loading operating system and data storage
Put the checks in your CI workflow
Run the same commands in CI that contributors use locally, with locked documentation and test dependencies. A practical sequence is:
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →- Install the project’s pinned documentation and test dependencies.
- Build the site with its normal builder and the warning policy used by the project.
- Run
sphinx-build -b doctest docs docs/_build/doctestfor marked Sphinx examples, or run the chosen MkDocs/pytest tests. - Fail the job when a required example fails or a page assertion does not pass.
GitHub’s guide to building and testing Python with Actions demonstrates running project build and test commands in a workflow. Adapt the action versions, Python matrix, caching, and deployment gates to your repository; the guide does not prescribe one configuration for every project.
Best Value
- Includes Raspberry Pi 5 16GB with 2.4Ghz 64-bit quad-core CPU (16GB RAM)
- Includes 128GB Micro SD Card pre-loaded with 64-bit Raspberry Pi OS, USB MicroSD Card Reader
- CanaKit Turbine Black Case for the Raspberry Pi 5
- CanaKit Low Noise Bearing System Fan
- Mega Heat Sink - Black Anodized
Decide which approach fits the project
The right check depends on what your documentation must prove. Sphinx’s native doctest builder executes examples marked with its directives. The documented MkDocs-Test workflow builds through pytest and supports assertions against generated pages. Evaluate these factors before choosing:
Quick Recap
- Which languages and code-block formats need to run.
- Whether examples require setup, expected-output comparisons, or conditional dependencies.
- Whether generated HTML needs checks beyond successful code execution.
- Compatibility with the supported Python, MkDocs, Sphinx, and plugin versions.
- Reproducibility across the environments you support, plus the ongoing maintenance and dependency-review burden.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
