dudebro249 / docrunner

A command line tool which allows you to run the code in your markdown files to ensure that readers always have access to working code.

Docrunner

A command line tool which allows you to run the code in your markdown files to ensure that readers always have access to working code.

What does it do?

Docrunner goes through your markdown file and runs any code in it, providing you safe testing for any markdown documentation. You can specify the path to the markdown file, along with other options, with flags.

Installation

Shell (Mac, Linux):

curl -fsSL https://raw.githubusercontent.com/DudeBro249/docrunner/stable/installers/install.sh | sh

PowerShell (Windows):

iwr -useb https://raw.githubusercontent.com/DudeBro249/docrunner/stable/installers/install.ps1 | iex

If none of these methods work, you can also install the docrunner binary from the releases. Make sure to add it to PATH so you can access it from anywhere

QuickStart

docrunner --help

Python Example

docrunner run --language python --markdown-path example/example.md --multi-file

This command executes all python within example/example.md and does so by putting each snippet of python from this file into a separate file, and running each file. If you don't want each snippet in a separate python file, just remove the --multi-file option.

Contributing and Local Development

Please check the CONTRIBUTING guidelines for information on how to contribute to docrunner.

Supported Languages

• python - docrunner run -l python
• javascript - docrunner run -l javascript
• typescript - docrunner run -l typescript
• dart - docrunner run -l dart

docrunner's Issues

Docrunner appends output

It would be benifical to have some flag, mode or usage that would run the code snippet and append or update the output expected on the snippet or below. This would ensure that the output expected would be as upto date as it could be and that if small wording changes have happened they would be reflected in the docs.

Add support for multiple markdown files

• Add support for multiple markdown files in docrunner.toml configuration file
• Change the markdown_path field to markdown_paths in docrunner.toml to allow support for lists.
• Add support for directories in markdown_paths

FileExistsError: Cannot create a file when that file already exists

When running a docrunner language command more than once on a given markdown file, a python FileExistsError if a second file write to an already existing file path is issued.

[ FIX ] Installation for mac and linux doesn't show up

For some reason the below doesn't show on the getting-started page.

Shell (Mac, Linux):

curl -fsSL https://raw.githubusercontent.com/DudeBro249/docrunner/dev/installers/install.sh | sh

Add configuration management with config file

• Use some sort of data serialization language, such as toml, yaml, or json to manage docrunner configuration and command line arguments

Deploy website to Firebase Hosting

• Deploy website to Firebase Hosting

Set testing up with pytest

• Write tests in the tests folder
• Set tests up with poetry and pytest

Add .sh installer

• An sh installer would be good for Linux and Mac users

Fix Bug in Docrunner File Comments

• Fix bugs in the way docrunner parses comments above snippets
• Fix bug in the way docrunner handles file comments. Docrunner should append to instead of rewrite code files if they are linked to more than once in a markdown file.

Documentation

• Add documentation for cli tool. Preferably done using a website, with docusaurus.

Dart support for CLI

• Add Dart language support for docrunner

Typescript Error TS6053: Typescript file not found error when running typescript code

Linux & Mac support

Currently docrunner only supports Windows, we should aim to support both mac and linux as well, this can be achieved by adding continuous deployment in the form of a Github workflow and release every time a branch is merged into the "stable" branch. In addition the shell install script must be fixed as this is installing a windows binary in a C drive on linux.

Support for ignoring certain snippets

• Allow docrunner to ignore specific code snippets in markdown files if they are prefixed with some sort of delimiter, such as <!--docrunner.ignore--> which also serves as a comment and won't be shown when rendering the markdown.

Add support for custom file names in markdown

• Users should be able to specify custom file names for snippets by prefixing the code snippet with <!--docrunner.file_name = "filename.py"--> on the line above the snippet
• The file name that is specified should only be used if the multi_file option is set to True, either through the docrunner.toml configuration file or through a cli argument

Rewrite Docrunner in Dart

• Rewrite the docrunner cli tool in the dart language

Why?

• It will allow the compilation into an exe which will not require python, or any language to be installed in order to run
• The cli tool will be faster

FileNotFoundError thrown when markdown file is not found

Add docstrings for most functions in project

• Add docstrings to most functions in order to increase code reusability