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