Choose Your Own Adventure style software documentation from markdown.
Markdown source, when parsed, outputs to a single HTML page.
Demo: http://lillian-seabreeze.github.io/adventuredocs/
We've included a demo! Checkout the testdocs/ directory! It
contains markdown files which represent sections, and an ORDER
file which specifies the default order of the sections.
All you have to do to get started is:
pip install -r requirements.txt .adocs testdocs outputfile.html
Then you can view outputfile.html in your web browser!
This repository is very conceptual and is in its infancy.
What we want to solve:
- Difficulty of maintaining a monolith of documentation
- Difficulty of reading a monolith of documentaiton
- Variablity of documentation, instructions which depend on specific needs, use cases, platforms, etc.
- Intimidation-factor of documentation
- Some other stuff I'm forgetting to put in here!
The main ways we'll solve those problems:
- CYOA-style static stite generator for software documentation!
- Each markdown file is a
<section>with a respectiveid(it's filename). - An
ORDERfile which specifies the default order NEXT_SECTION:if in its own paragraph in markdown, the proceeding list will be transformed into a list of links to other sections!- Progress bar!
- A way to set variables/user settings, e.g., "using_linux" to display content based on how a question was answered.
- A way to show/hide things within the section