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 code examples in a README, first decide which fenced blocks are meant to run, then use a runner that understands the language and format, and add its command to the project’s existing test or documentation build. There is no universal command for every language: Python doctest, Sphinx’s documentation-test extension, Rust’s rustdoc tests, and Markdown-aware tools such as Byexample suit different kinds of examples.
Start by deciding what the README is promising
A passing documentation test only verifies the examples your configured tool discovers and checks. Before choosing a runner, review the README’s fenced blocks and classify each one:
- Runnable example: code a reader can execute with stated prerequisites.
- Output: a result shown for illustration, not a command to execute.
- Configuration or pseudocode: a fragment that needs context or is not intended to run alone.
- External-state example: code that depends on a service, credentials, network access, or other changing state.
Write down the intended inputs, setup, and expected behavior for runnable examples. This inventory makes the test boundary explicit: a tool will not automatically validate every code-looking block just because it appears in Markdown.
Free tools Windows power users keep installed
One-click scans. No signup required.
Choose a runner that matches the language and format
| Route | Best fit | What it checks | Tradeoff |
|---|---|---|---|
Python doctest |
Interactive Python examples in docstrings or text files | Executes prompts and compares results with expected output | Uses doctest prompt syntax; it is not a general parser for every fenced Python block in arbitrary Markdown. |
Sphinx sphinx.ext.doctest |
Projects already building documentation with Sphinx | Runs marked setup and test blocks with the documentation doctest builder | Examples need appropriate directives or markup, and this fits a Sphinx workflow. |
Rust rustdoc |
Rust documentation examples | Runs language-native documentation tests | It is language-specific, not a general runner for mixed-language README fences. |
| Byexample | Documentation examples in supported languages and formats, including Markdown fenced blocks according to its project description | Executes snippets as regression tests | Check the current language support, syntax, setup, and CI instructions for your project before adopting it. |
| Test source included in documentation | Longer examples or projects able to include source files | Connects displayed code to a file that can be tested independently | The include mechanism and a test harness still need configuration; inclusion alone does not prove the complete README build works. |
Python: use doctest for prompt-and-output examples
Python’s standard-library doctest searches for interactive examples and can run them from a text file. For example, a README text file using the familiar >>> prompt format can be checked with:
#1 Best Overall
- Read Before You Buy — No Video Output: These adapters support charging and USB 2.0 data transfer, but cannot transmit video signals. Except for standard USB webcams (which use USB data only), they are not compatible with HDMI/DisplayPort cables, video-capable USB-C hubs, or docking stations with video output.
- Convert USB-A Ports to USB-C: Designed to connect USB-C earphones, cables, flash drives, card readers, and other USB-C accessories to standard USB-A ports. Plug-and-play with no drivers or software required.
- Aluminum Alloy Housing: Built with a sturdy aluminum alloy shell that aids in heat dissipation and protects against daily wear and scratches. Designed to maintain a stable and secure connection.
- Compact & Travel-Friendly: The ultra-compact design allows the adapter to stay plugged into your device without blocking adjacent ports or adding bulk, reducing wear and tear on your original USB ports.
- 12-Month Warranty: Backed by a 12-month manufacturer warranty for peace of mind. Designed to meet strict quality control standards for reliable everyday performance.
python -m doctest README.mdThe documented command-line form is python -m doctest [-v] [-o OPTION] [-f] file [file ...]. For a file that does not end in .py, the CLI infers text-file mode. See the Python doctest documentation for text-file use and options. Ordinary fenced Python code without doctest prompts is not automatically covered by this approach.
Sphinx: mark examples in a Sphinx documentation build
For a Sphinx project, sphinx.ext.doctest collects marked blocks and runs them through the doctest builder. Setup blocks run before test blocks; blocks can be grouped by document and group. Choose doctest-style examples when prompt interactions or intermediate values matter, and code-output-style examples when comparing output is useful. The Sphinx doctest extension documentation describes the supported markup and builder. The goal is to make sure “the documentation stays up-to-date with the code.”
Rank #2
- 5-in-1 USB-C Hub: Experience comprehensive connectivity featuring a Power Delivery input, two USB-A 2.0 ports, a USB-A 3.0 port, and an HDMI port. (Note: The USB-C power delivery input port is only for connecting an external wall charger to power your laptop and cannot power peripheral devices.)
- 90W Pass-Through Charging: Achieve optimal charging with 90W pass-through power to your laptop, supported by a total input of 100W, with the hub reserving 10W for operational efficiency. (Note: Wall charger not included.)
- Quick Data Transfers: Accelerate your productivity with rapid data transfers using a high-speed 5Gbps USB 3.0 port and two 480Mbps USB 2.0 ports.
- 4K HDMI Display: Enhance your visual experience with a hub capable of delivering 4K resolution at 30Hz in both mirror and extend modes. Please note that this hub is compatible with MacBook (macOS 12 and newer), Windows 10 and 11, ChromeOS, and laptops equipped with DP Alt Mode and Power Delivery. Note: This device is not compatible with Linux.
- What You Get: Anker USB-C Hub (5-in-1, 4K HDMI), welcome guide, 18-month warranty, and our friendly customer service.
Rust: use rustdoc for Rust documentation examples
Rust’s rustdoc supports language-native documentation tests. This is a natural option for Rust examples in documentation, but it is not a claim that rustdoc discovers arbitrary code fences in a mixed-language README. Follow the Rust rustdoc documentation-tests guide and establish how the examples are represented in your project.
Markdown with multiple languages: evaluate a Markdown-aware runner
Byexample’s project description says it can find examples in fenced Markdown blocks and other formats. That can be relevant when the README itself is the source of examples, but confirm that its current language support and configuration match your snippets before relying on it. See the Byexample project documentation.
Rank #3
- Sleek 7-in-1 USB-C Hub: Features an HDMI port, two USB-A 3.0 ports, and a USB-C data port, each providing 5Gbps transfer speeds. It also includes a USB-C PD input port for charging up to 100W and dual SD and TF card slots, all in a compact design.
- Flawless 4K@60Hz Video with HDMI: Delivers exceptional clarity and smoothness with its 4K@60Hz HDMI port, making it ideal for high-definition presentations and entertainment. (Note: Only the HDMI port supports video projection; the USB-C port is for data transfer only.)
- Double Up on Efficiency: The two USB-A 3.0 ports and a USB-C port support a fast 5Gbps data rate, significantly boosting your transfer speeds and improving productivity.
- Fast and Reliable 85W Charging: Offers high-capacity, speedy charging for laptops up to 85W, so you spend less time tethered to an outlet and more time being productive.
- What You Get: Anker USB-C Hub (7-in-1), welcome guide, 18-month warranty, and our friendly customer service.
Long examples: keep displayed code tied to tested files
When a README example is long or maintained as a standalone script, consider keeping the executable source in a file and including that file in the documentation where the builder permits it. Ray’s documentation guide, for version 2.58.0, distinguishes doctest-style examples, code-output-style examples, and literalinclude. It recommends doctest style for small examples where representations or intermediate values matter, code-output style for longer examples or when exact representations do not matter, and literal inclusion for end-to-end examples without outputs. The Ray examples guide also explains that inclusion is a way to show source, not a substitute for a test harness.
Make examples safe and repeatable
A documentation test should not quietly depend on a developer’s credentials, production data, or an unstable service. Make prerequisites explicit and prefer deterministic inputs and isolated test resources. Decide deliberately how to handle examples that cannot run in routine checks.
Rank #4
- Dual Converters, Infinite Potential：Includes 2× USB C male to USB A female adapters and 2× USB A male to USB C female adapters. Perfect for a wide range of uses—tablets with Bluetooth keyboards, expand USB ports on macbook, and more. Two different converters for all your daily needs
- Next-Level 10Gbps & 3A Charging: No more slow 480Mbps, this usb to usb c adapter has a transfer speed of up to 10Gbps, allowing you to do more transferring in less time. This usb adapter fits both USB A and USB C charger, supporting up to 3A fast charging
- Upgraded Exquisite Craftsmanship: With an aluminum alloy housing and metal connector, the usbc to usb adapter is extremely durable and sturdy. Rigorously tested to withstand more than 10,000 times of plugging and unplugging, ensuring long-lasting performance
- Broad Compatible: The usb c to usb adapter widely supports all USB C/ USB A devices like laptops, tablets, cellphones, car chargers, and phone chargers. Such as compatible with MacBook Pro/Air 2023/2022, Thunderbolt 4/3 Devices,Apple MagSafe Watch 9/8/7/SE/Ultra, iPad Pro 2022/2021, Samsung Galaxy S23/S20/S10, and iPhone 17/16/15 Pro. Plug and play
- Please Note: To reach 10Gbps speed, keep the cable under 3.3 ft. For USB A Male to USB C adapters, try flipping the USB C connector. USB C Male to USB A adapters support bidirectional 10Gbps transfer within 3.3 ft
- Keep secrets out of README snippets and test fixtures; use safe dummy values where appropriate.
- Do not point examples at production systems or data.
- For external services or unstable output, document the dependency and decide whether to skip, relax output matching, or keep the example outside the automated test boundary.
- When a block is skipped or excluded, make that status clear rather than implying that it is verified.
Ray’s guide notes that examples relying on external systems such as Weights & Biases need not be tested and documents skip controls and ellipses for unstable output. Those are options in that project’s documentation workflow, not a universal rule that every external dependency is safe to skip or ignore.
Add the check to the normal project workflow
Once a local command reliably runs the intended examples, add it to the repository’s existing test or documentation job so changes can reveal broken examples during routine work. Sphinx provides a doctest builder for marked snippets; Ray describes documentation snippets tested in CI. The useful integration point is the job contributors already use for tests or documentation, rather than a separate manual step that is easy to forget.
Best Value
- 5-in-1 Connectivity: Equipped with a 4K HDMI port, a 5 Gbps USB-C data port, two 5 Gbps USB-A ports, and a USB C 100W PD-IN port. Note: The USB C 100W PD-IN port supports only charging and does not support data transfer devices such as headphones or speakers.
- Powerful Pass-Through Charging: Supports up to 85W pass-through charging so you can power up your laptop while you use the hub. Note: Pass-through charging requires a charger (not included). Note: To achieve full power for iPad, we recommend using a 45W wall charger.
- Transfer Files in Seconds: Move files to and from your laptop at speeds of up to 5 Gbps via the USB-C and USB-A data ports. Note: The USB C 5Gbps Data port does not support video output.
- HD Display: Connect to the HDMI port to stream or mirror content to an external monitor in resolutions of up to 4K@30Hz. Note: The USB-C ports do not support video output.
- What You Get: Anker 332 USB-C Hub (5-in-1), welcome guide, our worry-free 18-month warranty, and friendly customer service.
- Run the selected command locally. Confirm that it finds the intended examples and reports mismatched output or execution failures.
- Add it to the existing test or docs job. Use the project’s current CI configuration and dependency setup; exact file names and labels vary by repository.
- Check the failure path. Change a harmless expected result or introduce a controlled failure in a disposable branch to confirm the job catches it, then revert the change.
- Keep the source aligned. Where the documentation builder supports inclusion, display tested source files instead of maintaining a second, drifting copy.
Keep the test boundary honest
Documentation checks cover only the blocks their configured extraction rules discover and the behavior their assertions compare. A Python doctest run can verify prompt examples it finds; a Sphinx builder can verify marked blocks; a language-native runner can cover examples represented in that language’s documentation format. Unmarked snippets, setup assumptions, and behavior not captured by expected output remain outside the check.
Revisit the inventory when examples change. If a snippet is not tested, label the reason and prerequisites so readers can distinguish a runnable, checked example from illustrative code.
Quick Recap
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.
