rst-extract [deprecated]
This tool is deprecated and no longer receives updates. It has been replaced by my doc-extract tool.
rst-extract is a tool for extracting specially tagged comments in Go
source code containing
reStructured Text. Both
grouped line comments (//
) and block comments (/* */
) are
supported.
How do I install this?
go get github.com/joeshaw/rst-extract
How do I use this?
Simply tag comments in your Go source code with +rst
as the first
line of your comment. For example,
package main
// +rst
// API Documentation
// =================
//
// (FIXME: add documentation)
Then run the rst-extract
command, providing it with a directory of
Go source files and an output directory:
rst-extract ./example /tmp/example
rst-extract will output one .rst
file per Go package.
Source files are processed in a predictable order:
- A file name matching the package name (for instance,
main.go
in amain
package) doc.go
- lexicographic order
Comments within a file are processed in the order they appear.
This predictable ordering allows you to add, for instance, a header to the output RST file by adding it to one of the special cases that are processed first.
Why would I want this?
I know what you're thinking. You're thinking these two things:
-
godoc
is awesome, what is the point of this? - RST sucks, Markdown is much better
And yes, you are right. However, in past Python projects I've used Sphinx and its excellent httpdomain extension for documenting HTTP APIs within my code. Godoc is not well-suited for this task, and while I prefer Markdown in general, RST is what Sphinx deals in, and its additional structure works well in this case.
In an ideal world I would have gone straight from Go comments to HTML for my API docs, and at some future point I might do that. In the meantime, however, this gets the job done for me, despite the messy Python dependency for Sphinx.
How does it work?
I hate writing parsers, and I am very thankful that I don't have to
write one for this. This builds upon the excellent code provided in
the Go standard library for parsing Go code, namely
go/parser
and
go/ast
.