Hugo as a code documentation tool

support
1

I’d like to use Hugo as a code documentation tool.

Specifically, I am maintaining a moderately complex puppet environment. Puppet used to have ‘puppet doc’ which sort of generated documentation from a puppet environment. They have switched to ‘puppet strings’ which appears to only generate on a per-module basis. Most of my puppet code is still using markdown, so Hugo is a good fit. Additionally Hugo has a syntax highlighter which is faster than calling pygmentize thousands of time.

Has anyone done something like this? What theme would you recommend?

Site layout based on puppet structure:

  • env1
    ** module 1
    *** manifests
    **** init.pp.md
    **** foo.pp.md
    *** templates
    **** foo.erb.md
    ** module 2
    ** …
    ** module 80
  • env2
    ** module 1
    ** module 2
    ** …
    ** module 80
  • …
  • env15
    ** module 1
    ** module 2
    ** …
    ** module 80

I have a script to generate the markdown from the puppet source code. It obviously will need to be tweaked based on the requirements of the theme I end up with.

I started with hyde-y because I liked the layout. I couldn’t get the envX or the homepage to render with any content - although the module and content pages rendered reasonably.

I have only been testing with one puppet environment at a time for efficiency of testing. I’ve tried a number of other themes with little success. hugo-theme-learn turned 27MB of source content into over 1G of output before filling the filesystem. A single page template like docuapi generated an unreadable huge document.

I originally generated the documentation in perl+pygmentize. It used perl’s HTML::Template. That is painfully slow and I found it hard to understand and tweak - even as the author. Unfortunately, it is looking attractive to go back to - given my difficulties with Hugo.

BTW - I come to this as a system admin who switched from being a developer almost 20 years ago. I program now mostly in perl and puppet with a smattering of other tools. I use someone else’s HTML as the basis to make my sites anything other than basic HTML 1.0.

My specific issue with ‘puppet doc’ and ‘puppet strings’ is it doesn’t show the source code. I want to pretty display the documentation - but also want the code to be easily accessible to my fellow admins so they spend less time logged into the puppet masters.