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.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
ci
examples
src
tests
.gitignore
.travis.yml
Cargo.toml
LICENSE
README.md

README.md

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 -->
    
    ```python
    {{< 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

Installation
$ cargo install blocktest
Usage
$ blocktest input_dir .md output_dir