autodoc
is a simple document generator. It parses docstrings for any function & generates markdown document.
👉 This is a very very lean & playground version of go/doc package.
autodoc
parses the docstrings for all functions in a given source code & generates markdown representation for them.
Note We are following the Numpy DocString Format.
To understand, how to write function docstrings following the numpy docstring format - checkout this excellent guide
Clone the repo & run the main
script.
go run main.go
It will loop through all the files in src
directory & generate a markdown file for each source file & store it in the docs
directory.
In the repo, I have added 2 source files. Executing the main
script, creates 2 new files in docs
directory.
.
├── docs
│ ├── fibonacci.md
│ └── square_root.md
└── src
├── fibonacci.go
└── square_root.go
Checkout the generated docs
The autodoc
exports a DocGenerator
method that takes in a filepath & generates a markdown of the same name in docs file. It does this by -
- Reads the source file
- Generates the Abstract Syntax Tree for the source code using the excellent
go/parser
package - Traverses the tree to find function nodes.
go/ast
stores them as FuncDecl nodes. It relies ongo/ast
to inspect the tree - Reads the docstring assosciated with it & the function name
- Formats it into a markdown representation
- Writes it to a file inside
docs
The main
script recursively loops over all the files in src
directory & applies all the previous step to each file