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/*

Project details

Release history Release notifications | RSS feed

This version

1.0.2

Mar 17, 2024

1.0.1

Mar 17, 2024

1.0.0

Mar 17, 2024

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

config-renderer-1.0.2.tar.gz (5.8 kB view details)

Uploaded Mar 17, 2024 Source

Built Distribution

config_renderer-1.0.2-py3-none-any.whl (6.8 kB view details)

Uploaded Mar 17, 2024 Python 3

File details

Details for the file config-renderer-1.0.2.tar.gz.

File metadata

Download URL: config-renderer-1.0.2.tar.gz
Upload date: Mar 17, 2024
Size: 5.8 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: twine/5.0.0 CPython/3.12.1

File hashes

Hashes for config-renderer-1.0.2.tar.gz
Algorithm	Hash digest
SHA256	`8e0996ea2696872f8b6ac31393ff53f0ebd99a6cf0ff9ed52ca54610ee8aa934`
MD5	`e649ec4378b212debc146900eb290987`
BLAKE2b-256	`3d6d017ab735b8450a1969a7ce56c473214c220b2bed07a8ca74de749b891792`

See more details on using hashes here.

File details

Details for the file config_renderer-1.0.2-py3-none-any.whl.

File metadata

Download URL: config_renderer-1.0.2-py3-none-any.whl
Upload date: Mar 17, 2024
Size: 6.8 kB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: twine/5.0.0 CPython/3.12.1

File hashes

Hashes for config_renderer-1.0.2-py3-none-any.whl
Algorithm	Hash digest
SHA256	`0852c8f2de67040e6d1bb075a20e0ccc65e8dfff5447237f2f5b10d5e8399281`
MD5	`7c7cb064a6c2bbbe5997be791cb51031`
BLAKE2b-256	`89f7f6a63de553c961c18f9b5e42504894c3e7ae408c96245741f2034e21e506`