https://github.com/jdkato/blocktest

:white_check_mark: A command-line tool for managing code snippets in documentation.
https://github.com/jdkato/blocktest

automated-testing continuous-integration documentation

Last synced: 2 months ago
JSON representation

:white_check_mark: A command-line tool for managing code snippets in documentation.

• Host: GitHub
• URL: https://github.com/jdkato/blocktest
• Owner: jdkato
• License: mit
• Created: 2018-02-21T17:44:56.000Z (almost 7 years ago)
• Default Branch: master
• Last Pushed: 2018-10-02T23:42:24.000Z (about 6 years ago)
• Last Synced: 2024-09-16T02:37:47.977Z (3 months ago)
• Topics: automated-testing, continuous-integration, documentation
• Language: Rust
• Homepage:
• Size: 37.1 KB
• Stars: 6
• Watchers: 3
• Forks: 1
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

        
# blocktest [![Build Status](https://travis-ci.org/errata-ai/blocktest.svg?branch=master)](https://travis-ci.org/errata-ai/blocktest) [![Crates.io](https://img.shields.io/crates/v/blocktest.svg)](https://crates.io/crates/blocktest)

`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](https://spacy.io/api/language#call). In this example, you want to include the following Python code snippet in your explanation:

```python

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:

    ```python

    # 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:

 

     ````

     

     ```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 ` begin` / ` 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

```shell

$ cargo install blocktest

```

###### Usage

```

$ blocktest input_dir .md output_dir

```