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.

6 comments

#umbrella #documentation #ex_doc #hexdocs

3 3075 6

2024-05-21 08:19:37 UTC

First 6 of 6 Posts

axelson

Scenic Core Team

I think the page with the documentation that you’re looking for is mix docs — ExDoc v0.40.3 which can also be accessed by running mix help docs. I agree that it could be easier to find. Do you remember which pages you were looking on? I’ll probably add a PR to add a link on Writing documentation — Elixir v1.20.2

To add a markdown file to the docs you need to use the :extras key as documented in mix help docs. Also I’m not clear how you’re running ex_doc. Typically for an umbrella project where you want to generate docs for all the applications together I believe that you would add ex_doc as a dependency to the umbrella itself. And then simply run mix docs from the umbrella root.

Post #1

fireproofsocks

My scanning started on ExDoc — ExDoc v0.40.3 – 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.

Post #2

fireproofsocks

That does not seem to work, at least not with extras defined in the umbrella’s mix.exs

Post #3

fireproofsocks

And also… if I try to run the mix docs from an app in the umbrella:

** (UndefinedFunctionError) function ExDoc.Config.default_formatter/0 is undefined (module ExDoc.Config is not available)

Docs: 1. Me: 0

Post #4

expilo

It’s 2024 and I’m still getting the same UndefinedFunctionError when I try to run mix docs in the umbrella. Has anybody figured out how to generate unified documentation for all the apps in the umbrella?

Post #5

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.

Post #6

— All posts loaded —