rebar3 hex docs: Improve error message when building custom docs

[wojtekmach]

I had the proper rebar.config setup:

    {docs, [{edoc_opts, [{preprocess, true},
                         {doclet, edoc_doclet_chunks},
                         {layout, edoc_layout_chunks},
                         {dir, "_build/default/lib/telemetry/doc"}]}

however I kept getting this error:

% rebar3 hex docs
===> Verifying dependencies...
===> No valid hex docs configuration found. Docs will will not be generated
===> Docs were not published since they couldn't be found in '/Users/wojtek/src/telemetry/_build/default/lib/telemetry/doc'. Please build the docs and then run `rebar3 hex docs` to publish them.

It wasn't clear to me how to fix the error.

Turns out I forgot to set {doc, "doc"} in src/<app>.app.src. (beam-telemetry/telemetry#86)

I wonder if we can somehow improve the error message?

[starbelly]

@wojtekmach #263 sorts some of this out, but it doesn't improve on the {docs, "doc"} bit (i.e., if it's missing). I don't know if that was always a convention in rebar3 projects prior to #180 but I don't believe there was, definitely not in rebar3_hex (AFAIK). That PR introduced a lot of problems :)

Need to make a decision on whether to even honor that in v7. On one hand, I suppose it's convenient, on the other hand, it's a bit "dangerous", as were the changes in the PR mentioned above (i.e., you can have stale docs lying around and inadvertently publish them). In v7 the goal is to be like mix and ex_doc that everything must be explicit. So for this case, and in case there is still no ex_doc provider around, what do you think is amenable?

Specifically in #221 I have a task to add a --doc-dir vs relying on {doc, Dir} attribute in .app.src; all in effort to make make it all quite explicit. I hope most won't even use that option, but it'll be there for the cases that require it.

[max-au]

I just ran into this very issue with the newest rebar3 (from master branch) attempting to publish erlperf - https://github.com/max-au/erlperf

It felt a bit frustrating as the actual package has been published, and then the error occurred. It feels safer to fail the entire operation (not even attempt to publish the package if docs provider is broken, unless I explicitly specify --without-docs).

I eventually succeeded with this command: rebar3 hex publish docs --doc-dir doc but the error message is indeed confusing.

[starbelly]

@max-au Are you on the latest rebar3_hex? There were a lot of fix ups and changes in behaviour in v7

Edit:

Even if you are on the latest, the behavior you desire is to fail fast if no doc provider has been configured?

We may able to make that configurable, but the default behavior is indeed to just publish the package without docs. I do like failing fast without docs, but the behavior was made so to align with mix hex. I think if switched our tune, we'd have to do a new major version, maybe not...

A few notes:

1. rebar3 hex v7 comes with the build provider so you can see what will happen and what will be uploaded to hex without publishing
2. You can always publish docs after the fact (i.e., packages become immutable, but not docs).

[starbelly]

This was discussed, and I think I agree with what was put out there, specifically. We can do this in stages.

1. Start with a warning before the confirmation prompt about no doc provider configured, etc and in future versions this will be required.
2. Provide a way to disable the warning
3. Make the change to raise an error if a doc provider isn't configured.

Still though, you used docs-dir option, so in your case there is no provider?

[tsloughter]

I just hit this.

I have docs in doc/ and the error message given by rebar3 hex publish doesn't mention anything about how to publish when that is the case, it only talks about doc providers.

[starbelly]

@tsloughter Are you sure you're on the latest and I guess, let me ask what was your exact cli usage and your expectation. If I run rebar3 hex --doc-dir src :

===> No doc provider configuration was found, therefore docs can not be published.

You may resolve this by adding a doc provider property to your projects hex config.

To configure rebar3_ex_doc as your doc provider (recommended but requires >= OTP 24)

Add the following configuration to your rebar.config :

{project_plugins, [rebar3_ex_doc]}.

{hex, [{doc, ex_doc}]}.

{ex_doc, [
          {source_url, <<"https://github.com/namespace/your_app">>},
          {extras, [<<"README.md">>, <<"LICENSE.md">>]},
          {main, <<"readme">>}]}.

Alternatively if using OTP < 24 or you prefer edoc, add the following to your rebar.config :

{hex, [{doc, edoc}]}.

If you always intend to publish packages without docs and wish to silence this warning you should use :

rebar3 hex publish package

Note : In version 7.1 this warning will be treated as an error

Edit:

Misunderstanding. You need an error for when a docs dir exists, but no --doc-dir switch was given and you need to be informed about that. So we can check to see of docs exist, if it does, and you have no doc provider configure, just error out with use --docs-dir option or rather, include that as part of the warning message above perhaps. Thoughts?