Throughout a current company hackathon, my group’s charter was to enhance the documentation for the Steampipe plugin SDK. Like other elements of the Steampipe system, the plugin SDK is written in Go and published to pkg.go.dev. The version that existed when we began is here. As is normal, the documentation was an autogenerated brochure of functions and types. To describe how to use those functions and types, we offered guidance on the steampipe.io site.Our hackathon
challenge was to weave such assistance into the generated documents. If you’re composing a Steampipe plugin, your list of jobs looks like this:
- Define the plugin
- Produce the plugin entry point
- Define your very first table
- …
These tasks require that you use functions and types, but while remarks connected to those functions and types can boost the generated paperwork, they’re too granular for the high-level exposition we aimed for. Searching for motivation, Steampipe lead designer Kai Daguerre discovered that our high-level page did not have the introduction section he saw in the paperwork for pgx, a Go motorist for Postgres.That introduction comes
from https://github.com/jackc/pgx/blob/master/doc.go, which is one long comment(that uses Go remark syntax)followed by a plan declaration.So we included a doc.go at the top level of our repo to produce this overview. IDG Composing a wiki in Go remarks We utilized the name doc.go because that seems to be traditional, however it might have been called foo.go. What’s salient is that it’s a valid Go file that comes from a package. The plan consists of no code, just documentation. We wrote headers to develop the sections of the introduction, and in each section we described a plugin author’s task using narrative, inline code examples, internal links to functions and types, and external links to examples somewhere else. The capability to link within the code’s namespace was a revelation. To explain the job called Include hydrate functions, for example, we composed this: # Include hydrate functions A column might be occupied by a List or Get call. If a column requires data not offer by List or Get, it may specify a [plugin.HydrateFunc] that makes an additional API call for
each row. Add a hydrate function for a column by setting [plugin.Column.Hydrate] The section definedby the Include hydrate functions header is a link target: Add hydrate functions. And the bracketed products render as links to a type, plugin.HydrateFunc, and to a residential or commercial property, plugin.Column.Hydrate. This was beginning to seem like wiki composing! What we still lacked, though, was the capability to develop brand-new wiki pages where we might explain higher-level concepts. The overview was one place to do that, however we wanted to book that for narration of the plugin author’s journey. Where could we go over an idea like dynamic tables, a sophisticated function that allows plugins like CSV which have no fixed schema and must specify columns on the fly?Kai realized that not just might we produce brand-new documentation-only bundles for such topics, we could also import them so that their names were offered for the exact same sort of shorthand linking we might do with, e.g., [plugin.HydrateFunc] In the high-level
doc.go he did this: bundle steampipe_plugin_sdk import
(“github.com/turbot/steampipe-plugin-sdk/v5/docs/dynamic_tables” )var forceImportDynamicPlugin dynamic_tables. ForceImport And in/ docs/dynamic _ tables/doc. go he did this: plan dynamic_tables type ForceImport string Now we might compose a sentence in a remark like this:/ * Use [dynamic_tables]https://hub.steampipe.io/plugins/turbot/csv”>. when you can not know a table’s schema beforehand. */ plan steampipe-plugin-sdk And the bracketed term autolinks similar to any other name in the code’s namespace.If that seems like more difficulty than it deserves, you can avoid the import gymnastics and just utilize an external link:/ * Utilize [dynamic_tables] when you can not understand a table’s schema ahead of time. [dynamic_tables]: https://pkg.go.dev/github.com/turbot/steampipe-plugin-sdk/v5/docs/dynamic_tables */ bundle steampipe-plugin-sdk Either way, the authoring experience
now feels more completely wiki-like. You can produce brand-new
pages as needed, and weave them into the hypertextual
paperwork that lives within the code base.It was, admittedly, a little bit of a battle to use the Go system in the ways explained here. The remark syntax is Markdown-like however frustratingly not Markdown; it depends on many implicit formatting conventions . If you go this route you’ll need a regional previewing tool, and it
‘s not super-obvious that the one you desire is not godoc however rather pkgsite. Had we discovered the command go set up golang.org/x/pkgsite/cmd/pkgsite@latest we would have conserved ourselves a lot of grief. How is this literate programming?It isn’t! In his eponymous paper Knuth wrote: The specialist of literate programming can be regarded as an essayist, whose primary concern is with exposition and quality of design. Such an author, with thesaurus in hand, selects the names of variables thoroughly and discusses what each variable ways. He or she pursues a program that is comprehensible because its
principles have actually been introduced in an order that is finest for human understanding, using a mix of official and casual techniques that enhance each other.To support this practice he invented a system called web whose components, tangle and weave, allowed the author of a program to inform its story in a language that combined code(originally, Pascal )and documentation(originally, TeX )in a narrative-first method. Our modern-day methods of mixing code and documentation, and creating docs from ingrained comments, just superficially resemble
Knuth’s practice, as Mark Jason Dominus mentioned in his essay POD is not Literate Setting
(2000). And yet, now that our hackathon workout has given me a taste of what code-as-wiki can be, it does seem like an action toward the storytelling approach that Knuth advocates. Remember that he called his system web before there was the web we now populate, never ever mind wikis! I can’t claim that we’re now literate programmers in the Knuthian sense, and I have actually always questioned if just a Knuthian mind could implement that initial vision. But by doing this of enhancing the narrative quality of autogenerated docs does feel like an action in
the best direction. Copyright © 2022 IDG Communications, Inc. Source