Generating Go docs using gomarkdoc and pandoc
I recently had to distribute the documentation of an internal library to users. Go developers are used to their editor to providing them with auto completion, usually with the help of gopls. A lot of times it is necessary for users to be able to browse a comprehensive list of methods and data types available for reference. For open source projects, we rely on godoc.org and pkg.go.dev. But unfortunately, it is not easy to host one for internal projects.
After a bit of searching, I found princejef/gomarkdoc. This project is able to process packages and use the docs, to generate a markdown file. Using this I was able to produce a markdown of the packages I wished to share with the users.
# install as a cli-tool go get -u github.com/princjef/gomarkdoc/cmd/gomarkdoc # generate the docs using specific packages gomarkdoc ./pkg/foo \ ./pkg/bar \ ./pkg/lorem/ipsum > docs/user-docs.md
This was good enough, but a better way would be to distribute it as a single
html file. Pandoc is a swiss army knife, which can convert one markup format to
another. Combining this into the pipeline, I was able to generate an
which has the documentation, which is viewable in the browser and contains links
to the git repository as well.
To make the web document look good, I found two interesting things.
The first being, sakura.css, which is a
classless css stylesheet, which can be
applied to any
html file and make it look like a modern website.
The second useful thing, are a few flags available in
pandoc which help with making the documentation
html file truly standalone.
- –css: This flag accepts a link to a
- –self-contained: This flag produces the
htmlfile in a way, such that no external dependency is needed.
Using these flags, we can come up with the following script to generate the
html file from the markdown file.
pandoc docs/user-docs.md \ --toc \ --metadata title="My Package - User Docs" \ -c https://unpkg.com/sakura.css/css/sakura.css \ --self-contained \ -o docs/user-docs.html
This results in well rendered documentation which is standalone and looks modern as well.