Generate HTML documentation from dotfiles
Project description
config-renderer
config-renderer is a Python CLI utility that reads a configuration file and optional CSS stylesheet and renders a nice looking HTML page from it.
See example documentation page in https://hamatti.github.io/config-renderer/
Motivation
I like to document my configuration files well so I can understand and remember them well. I also like sharing my configurations in the web and I wanted a way to write configuration files that are human-readable and computer-understandable. With this renderer, I can run a single command to generate an HTML page from the source file so I don't need to maintain two separate documentations.
Usage
You can run config-renderer with pipx run config-renderer
Configuration renderer
Renders a configuration file into an HTML page based on custom minimal markup language.
Supports any config file where comments start with #.
Usage:
config-renderer.py <configfile> [-s <stylesheet> | -b] [-o <outfile>] [--class-prefix <prefix>]
Options:
-s --style <file> Filename of a stylesheet to be added
-b --body-only Don't add html, head and body elements. Meant for embedding to existing sites.
-o --output <file> Filename for where to write the file [default: config.html]
--class-prefix <prefix> Customize CSS class prefix [default: configuration]
Markup:
- First line should start with "# HEADING" where heading gets added to <h1> and <title>
- # [Heading 2] -> <h2>Heading 2</h2>
- #> class -> <div class="class">
- #< <- </div>
- #~ Any line starting with #~ is ignored by the parser.
- # Any line starting with a # that does not match any of above, will be added into a <p>paragraph</p>. An empty line, a config line or any of the above will wrap up the paragraph.
Custom markup
First line needs to start with # TITLE that is turned into <h1>TITLE</h1> and <title>TITLE</title>
| Markup | Output | Notes |
|---|---|---|
# [Heading 2] |
<h2>Heading 2</h2> |
|
#> class |
<div class="class> |
|
#< |
</div> |
|
#~ |
(nothing, lines are ignored) | |
# anything else |
<p>anything else</p> |
Multiple consecutive lines with # are combined into same paragraph |
any line not starting with # |
<pre><code>any line not starting with #</pre></code> |
Multiple consecutive lines are combined into same code block |
[Website title](website url) |
<a href="website url">Website title</a> |
|
https://example.com |
<a href="https://example.com">https://example.com</a> |
Custom styling
You can provide your own CSS file with --style FILENAME option. The styles get added to the <head> of the document so the end result is self-standing package.
The tags are marked with following classes:
| Tag | Class |
|---|---|
h1, h2 |
configuration-heading |
a |
configuration-link |
pre |
configuration-pre |
p |
configuration-paragraph |
div |
configuration-container |
You can customize these with the --class-prefix PREFIX option where PREFIX replaces configuration in above examples.
Example
File called example.conf
#+ Juhis' tmux configuration
# [Install plugins]
#~ A list of the plugins
# [Tmux Plugin Manager](https://github.com/tmux-plugins/tpm) to install other plugins
set -g @plugin 'tmux-plugins/tpm'
set -g @plugin 'tmux-plugins/tmux-resurrect'
ran with
pipx run config-renderer.py example.conf
results in
<!DOCTYPE html>
<html>
<head>
<title>Juhis' tmux configuration</title>
<style></style>
</head>
<body>
<main>
<h1>Juhis' tmux configuration</h1>
<h2>Install plugins</h2>
<p>
<a href="https://github.com/tmux-plugins/tpm">Tmux Plugin Manager</a> to
install other plugins
</p>
<pre><code><span>set -g @plugin 'tmux-plugins/tpm'</span>
<span>set -g @plugin 'tmux-plugins/tmux-resurrect'</span>
</code></pre>
</main>
</body>
</html>
Build and upload to PyPi
Update version number in pyproject.toml
rm -rf dist/
python -m build --sdist
python -m build --wheel
twine upload dist/*
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 config_renderer-1.0.2-py3-none-any.whl
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 0852c8f2de67040e6d1bb075a20e0ccc65e8dfff5447237f2f5b10d5e8399281 |
|
| MD5 | 7c7cb064a6c2bbbe5997be791cb51031 |
|
| BLAKE2b-256 | 89f7f6a63de553c961c18f9b5e42504894c3e7ae408c96245741f2034e21e506 |
