Docout: flexible documentation generator

Your Libraries & OS Mentoring Libraries
, ,
1

Recently I could no longer put off the task of creating some internal documentation so that FE developers would be able to more easily integrate a React app with our API. Meanwhile I have been in the process of porting over some documentation of a public facing API that used OpenApi spec (generated with rswag) to Phoenix.

I hadn’t really enjoyed the experience of learning a custom DSL and fighting weird syntax differences and missing features, and OpenApi seemed like overkill for a small internal API anyway, so I decided I wanted a different approach. After a quick survey of existing option I decided to create a tool that would allow me to:

  1. Write specs in a format I found convenient and easy to parse/update when working in code
  2. Generate different docs for different audiences
  3. Update generated doc files automatically

The result is docout: GitHub - tfwright/docout: Generate documentation files from your existing Elixir app docs at compile time.

As you will see if you go through the code, it is very simple, basically just a glorified compiler task that parses module docs, formats them, and then prints them to a file. I am using it to configure which modules should generate which docs (external vs internal api) and use the excellent OpenApiSpex side by side with my own custom doc format which uses a version of Slate, which I like because it uses markdown files for easy viewing when in the code as well as a web interface.

Hopefully others may find this useful, please let me know your thoughts in any case!

Cheers

7 Likes
2

The latest update contains some breaking changes to be aware of before updating. The parsing logic and output path overrides have been moved from app config to use keyword opts to be more in line with official Elixir library guidelines.

For an example of how to migrate output_path options see this commit: Update docout · tfwright/live_admin@4b56d50 · GitHub

Migrating the parsing logic is similar. Just remove the relevant config from config.ex and pass the parse_function to the use options as demonstrated in the advanced usage docs.

Note that even if you are not using either of these options you should replace @behaviour Docout.Formatter with use Docout to avoid breakage.

For those of you who are unfamiliar with the library, I revamped the docs as well if you want to a rundown of what it’s about. Feel free to raise any questions or make suggestions here. I am hoping to get around to packaging a hex release soon.

Cheers!

1 Like