A command-line tool for managing code snippets in documentation.
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


blocktest Build Status Crates.io

blocktest is a "preprocessor" for markup (e.g., Markdown or reStructuredText) code blocks. It allows you to keep your code and prose separate without duplicating work. The idea is simple: blocktest extracts your code examples from within a larger testing context and adds them to your markup at user-specified locations.

For instance, let's say that you're writing this section of the spaCy documentation. In this example, you want to include the following Python code snippet in your explanation:

doc = nlp(u'An example sentence. Another sentence.')
assert (doc[0].text, doc[0].head.tag_) == ('An', 'NN')

With blocktest, you need two files:

  1. A Python test file with the snippet inside of its test-related boilerplate:

    # test_language.py
    import spacy
    nlp = spacy.load('en')
    def test_example():
        doc = nlp(u'An example sentence. Another sentence.')  # example1 begin
        assert (doc[0].text, doc[0].head.tag_) == ('An', 'NN')  # example1 end
  2. A markup file which specifies where to find the snippet:

    <!-- example.md -->
    {{< id="example1" src="test_language.py" >}}

blocktest will scan example.md looking for block definitions, which specify a unique ID and a source file for each snippet. It will then extract the snippet (as indicated by the <id> begin / <id> end comments) from the source file and substitute it back into your markup. This allows you to write a thorough test suite for your code examples without having to maintain multiple copies of the same snippet.

Getting Started

$ cargo install blocktest
$ blocktest input_dir .md output_dir