tfwright
Docout: flexible documentation generator
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:
- Write specs in a format I found convenient and easy to parse/update when working in code
- Generate different docs for different audiences
- 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
Most Liked
tfwright
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!
Popular in Libraries
Other popular topics
Latest on Elixir Forum
Sponsor Spotlight
Catch errors, track performance, monitor hosts and more.
Categories:
Sub Categories:
Forums
Our Sponsors
Build Elixir applications with speed and confidence.
Supporting innovation across the BEAM ecosystem.
We build reliable cloud platforms for business-critical systems.
Catch errors, track performance, monitor hosts and more.
Practical resources that improve the lives of professional developers.
Enabling companies to succeed by building software people love.
The deployment platform built for Elixir: PaaS ease, VPS control.
Courses that'll move you from confusion to "Aha, now I get it!"