Turn all the markdown files in your repos into one big, divio structrured documentation
Project description
Divio Docs Generator
Automatically collect, aggregate and structure all your divio-style documentation into a tree of .md files.
/{reponame}
/tutorials
/how-tos
/explanations
/references
- Any input structure: this script will scan your entire repository for .md files
- If you have a how-to section in your README, that'll get extracted and put in the right spot
- Or, if you have an how-to.md file, it'll get added in its entirety!
- Any output structure: this script generates a simple markdown tree. Nothing proprietary, no vendor-lockin. It can be generated from GitHub Actions and put into a Jekyll pages site just as easily as it is run from a Raspberry Pi and used to render the contents of an Ember application.
All you have to do is simply name your headers and/or files after the divio sections (tutorial
, how-to
, explanation
, reference
). (Oh, don't worry, the search is done through a case insensitive regex. Add more words as you please)
Getting-Started / tutorial
(You can also use the repository template!)
- Clone the repository using
git clone https://github.com/Denperidge-Redpencil/divio-docs-gen.git && cd divio-docs-gen
- Install the pre-requirements using
python3 -m pip install -r requirements.txt
- Setup the docs.conf file (See the reference below and/or the docs.conf.example file)
- And finally, run using
python3 app/index.py
!
How-To
Build & install package locally
python3.10 -m pip install --upgrade build setuptools
python3.10 -m build
python3.10 -m pip install --force-reinstall ./dist/*.whl
Note: other Python versions can be used!
Discussions
The Divio structure is built upon splitting your documentation into 4 types of documentations. . In this repository they're referred to as sections.
If you want to know more about the design principles of this project, feel free to check out my writeup here!
Reference
docs.conf
[DEFAULT] section
This section is on the top of the file, and defines options that affect the entire configuration
Parameter | Functionality |
---|---|
DefaultOwner | (string) Defines which user or org has to be checked for the repository in case its Path does not explicitly define an owner |
GenerateNav | (boolean) Whether to add internal navigation to the top of each generated file. Defaults to False |
DocsBasedir | What folder to output the docs in. Defaults to docs/ |
Tutorials | Sets the output folder name for tutorials. Defaults to tutorials |
How-tos | Sets the output folder name for how-tos. Defaults to how-tos |
explanations | Sets the output folder name for explanations. Defaults to explanations |
references | Sets the output folder name for references. Defaults to references |
[repo] section
You can add as many of these as you want. Each one represents a repo you want parsed. You can give any name to [the-section-header]
, but you should probably avoid duplicates. If no repo sections are defined but you've defined DefaultOwner, all repos of that user or organisation will be parsed.
Parameter | Functionality |
---|---|
Path | (string) Defines which repository to parse |
Copy | (array) Files in the repository that should be copied to a specific section. Syntax: file.md/sectionname,file2.md/sectionname |
Ignore | (array) Files in the repository that should be ignored. Syntax: file.md,file2.md |
Note: for Copy
and Ignore
you can choose to be more specific by writing sub/folder/filename.md
. The check is a provided_path in full_filepath
, so sub/folder/filename.md
will apply to even/further/sub/folder/filename.md
.
Allowed Path syntax
You can use any of the following!
reponame
(if DefaultOwner is defined)reponame@branch
(if DefaultOwner is defined)owner/reponame
owner/reponame@branch
Synonyms
For ease of use and freedom of implementation, every section has synonyms.
Section | Synonyms |
---|---|
Tutorials | Getting started |
How-To's | How-To, Guide, Usage |
Explanation | Discussion, background material |
Reference | Technical |
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for divio_docs_gen-0.0.3-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 5bccf1eaed8db0c67f008ac3289b2d052cb5bf45097fc9c6bca4f15c81b52c08 |
|
MD5 | 04bbd811a705446cb269c872a6e84030 |
|
BLAKE2b-256 | 1069d1385ef46d6bc9ddaa0c6883751ea4f0bf26d2c0d4a7699f05944a4be7e9 |