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. · GitHub
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
Trending in Announcing
Other Trending Topics
Latest on Elixir Forum
Sponsor Spotlight
Practical resources that improve the lives of professional developers.
Categories:
Sub Categories:
Forums
Popular Tags
- #ecto
- #liveview
- #troubleshooting
- #learning-elixir
- #deployment
- #library
- #erlang
- #testing
- #genserver
- #mix
- #absinthe
- #remote-other
- #otp
- #plug
- #how-to-question
- #macros
- #postgres
- #channels
- #elixirconf
- #exunit
- #discussion
- #code-sync
- #javascript
- #podcasts
- #onsite
- #dialyzer
- #docker
- #authentication
- #umbrella
- #full-time-contract
- #podcasts-by-brainlid
- #ecto-query
- #elixir-ls
- #phoenix_html
- #iex
- #blog-post
- #graphql
- #genstage
- #ai
- #elixirconf-us
- #websockets
- #supervisor
- #advent-of-code
- #distillery
- #processes
- #api
- #forms
- #metaprogramming
- #performance
- #security
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.
Error tracking, logs, uptime, and Just Enough APM. Built for developers.
Practical resources that improve the lives of professional developers.
Develop your skills with books, videos, and courses.
Enabling companies to succeed by building software people love.
The team behind Membrane, Popcorn, LiveDebugger. Available for hire.
Courses that'll move you from confusion to "Aha, now I get it!"
First Post!
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
usekeyword opts to be more in line with official Elixir library guidelines.For an example of how to migrate
output_pathoptions see this commit: Update docout · tfwright/live_admin@4b56d50 · GitHubMigrating the parsing logic is similar. Just remove the relevant config from
config.exand pass theparse_functionto theuseoptions as demonstrated in the advanced usage docs.Note that even if you are not using either of these options you should replace
@behaviour Docout.Formatterwithuse Docoutto 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!