galaxyproject / galaxyproject/planemo

Convert Docs to Tests and Example Notebooks

Open
#703 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
110
Forks
102
Avg merge
4d 21h
Merged PRs (30d)
13

Description

https://github.com/galaxyproject/planemo/pull/699/files added some ad-hoc tests generated from documentation manually but I think this process should be made automatic.

I'm imagining a fairly simple two step process - collection and output.

- During the first step we simply take a list of RST docs to pull commands from - commands are just lines of RST in "code" blocks that start with "$" (extending the line if it ends with `\`).
- During the second step we could generate bash scripts for testing and a Jupyter notebook displaying the output. If we placed the bash scripts in the repo - we could execute them from planemo-machine to test the documentation and if we placed the Jupyter notebook in repo we could use nbviewer and have awesome extra interactive docs for exploring Planemo.
- To generate the bash script we would set the same header used now at the top of the file, list the preconditions for that doc, and then list the commands. We'd have to annotate commands that we expect to fail in the RST so we could appent ``|| true`` or something to them.
- To generate the notebook - I'm imaging using [notedown](https://github.com/aaren/notedown) with the same preconditions and commands - I'd just wrap each command with a Markdown codeblock and prepend ! to commands.

```python

!mkdir tool_init_exercise
!cd tool_init_exercise
!wget https://raw.githubusercontent.com/galaxyproject/galaxy-test-data/master/2.fastq
!seqtk seq -A 2.fastq > 2.fasta
!cat 2.fasta
```

Contributor guide

Open the contributing guide

Research direction

Start by reviewing the files changed in pull request 699 and locate the existing ad-hoc documentation tests. Define collection from RST code blocks beginning with "$" and output as bash scripts and a Jupyter notebook, including documented preconditions and expected-failure annotations. Done means the process automatically produces both outputs from selected documentation.

Written by the indexing model from the issue text.

Assessment

Tech stack
jupyter-notebook, python
Domain
documentation, testing, tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.