Untangle special markdown blocks from docstrings and assemble them into a static webpage.
Project description
Doc Note Untangler
A tiny tool for extracting special blocks from docstrings and embedding them in a static web page.
See an example here.
Motivation
Good documentation can be invaluable in the long term, but it takes effort which can be difficult to justify in the short term. Not all projects are expansive libraries or frameworks, often they're just small applications with just a couple of pieces of critical business logic. In those cases especially it may be tempting to forgo external documentation, which will of course bite you right back when it comes to onboarding new people or having to explain a particular behavior to your stakeholders over and over again.
We have plenty of tools for building and hosting static pages and wikis from dedicated files but when it comes to documenting business logic, they require extreme vigilance to avoid discrepencies between docs and actual behavior. Misleading docs are often worse than no docs at all.
To avoid accumulation of discrepencies over time, it helps to put your docs near the code itself, so the engineer who modifies it can quickly spot new inaccuracies in docs and fix them.
Module, class and function docstrings are a fine place for such docs, and this tool will let you easily define which parts of them may be relevant to external users and generate a static page for them.
Details
When not to use this tool:
- You're documenting a library, framework or a complex application
- You're generating reference manuals for your api
When you may want to use this tool:
- Your application contains a several pieces of logic which should be documented externally
Usage
python -m doc_note_untangler.cli <directory>
Examples
The notes extractracted from this very project are hosted at github pages. You will find the relevant docstrings in the source code.
Configuration
The CLI application offers some basic configuration such as setting the source paths and output dir.
See python -m doc_note_untangler.cli --help
for all options.
If you desire more complex customization, copypaste the source code into your own project and modify it at will.
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 doc_note_untangler-1.0.1-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | a80ec1a368fe1259916e4170e27abfe042af3a037f073abaa580805e09392e4e |
|
MD5 | 0cf4b32a71e9df52529c8429dd4105a4 |
|
BLAKE2b-256 | d64f774ec172184342e7a6582341a6477fc47f89db5b09ee699b1a885d0fa05c |