fireproofsocks
Generating docs (ex_doc / ExDoc) for an Umbrella App
What needs to be done to make ExDoc play nice with an umbrella app? I can run something like
ex_doc "My Umbrella" "1.0.0" "_build/dev/lib/my_app/ebin/"
But you have to choose one of the component apps out of the _build directory, which feels pretty arbitrary.
Also, I’m not having much luck adding in my own markdown files to the docs… it’s well and good that my entire app gets crawled and docs are added for each and every module, but more important to me (and arguably to users) are the comments and explanations that exist primarily in stand-alone markdown files. I’ve tried copying tactics seen for the Phoenix repo, but ironically, I don’t see that those “extra” and “groups_for_extras” are documented anywhere.
Most Liked
fireproofsocks
My scanning started on https://hexdocs.pm/ex_doc/readme.html – I firmly believe that examples are paramount. Everything else is a nice-to-have. So I would clarify the def project do .... bit (clarify that this is from your mix.exs, and I would definitely include at least one more example that demonstrated the additional options that are available to the configuration (e.g. the groups_for_extras).
The way that page is structured, I completely missed the tiny link to mix docs and instead zeroed in on the ex_doc escript part. If the mix docs tool is the normal way of doing things and the ex_doc script more of an alternative, then perhaps the formatting should correspond with that intended usage.
When I tried mix docs in my umbrella app, all my extras could not be found… should those be listed in each project in the repo or in the mix.exs at the root of the umbrella? It’s possible to have 2 very different presentations depending on whether you’re viewing an individual app or the umbrella as a whole.
api-reference.html – what is that and why would I want it created or not?
I think the big thing with the umbrella is that all paths seem to off… I’m not sure if they’re supposed to be relative to the individual apps and I’m supposed to be doing all this docs configuration in the individual apps or not.
Sorry to be terse.
LostKobrakai
I’m not sure on the progress, but I’ve heard this is on the roadmap given OTP adopted ex_doc and it’s also in need for consolidated multi app documentation.
Popular in Questions
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.
Develop your skills with books, videos, and courses.
Producing high quality Elixir screencasts since 2017.
Courses that'll move you from confusion to "Aha, now I get it!"