autodoc – A simple document generator

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.

❓ What is it?

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

🚀 Demo

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

🤔 How?

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 –

1. Reads the source file
2. Generates the Abstract Syntax Tree for the source code using the excellent go/parser package
3. Traverses the tree to find function nodes. go/ast stores them as FuncDecl nodes. It relies on go/ast to inspect the tree
4. Reads the docstring assosciated with it & the function name
5. Formats it into a markdown representation
6. 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

GitHub

View Github