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.
1 Like
I think the page with the documentation that you’re looking for is https://hexdocs.pm/ex_doc/Mix.Tasks.Docs.html 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 https://hexdocs.pm/elixir/writing-documentation.html
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.
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.
That does not seem to work, at least not with extras defined in the umbrella’s mix.exs
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
