Safer default behavior for publishing.

[starbelly]

We recently merged a PR that alters the behavior when it comes to publishing packages and docs (see #177 and #180 ).

As part of the conversation around that PR are some of my thoughts one where to go from here:

The current behavior of rebar3_hex is to attempt to publish both package and docs. We publish the package and then attempt to publish the docs. As part of #180 we will not attempt to publish docs if a docs dir is not found.

I think we should strive for parity with hex (mix hex) here. Specifically, we should check that docs exist before we attempt to publish anything, if they do not, bail and give the user a message vs publishing the package and then trying to publish docs. This makes a publishing package and docs somewhat atomic.

To go with this we should provide switches for the publish command that allow a user to indicate explicitly that they only want to publish one or the other, such as --package and --docs.

[tsloughter]

Does "not attempt to publish docs if docs dir is not found" refer to after having run rebar3 edoc? If that is the case, then that is fine. But if it checks for a docs dir before running edoc that is wrong.

But yea, strive for parity with mix hex.

[starbelly]

@tsloughter yeah, wasn't very clear there and thoughts are bit muddy per the recent change.

Looking again, the operation doesn't seem to be exactly as I described. I looked at the code a few weeks ago, but it doesn't align with what I had thought of today :

https://github.com/hexpm/hex/blob/771386942f4e5a928153040b22426916c5fa522c/lib/mix/tasks/hex.publish.ex#L182

So, they do try to publish the package first, then publish the docs, but there's a key difference in that you can somewhat guarantee the docs will get built, iirc mix hex.publish will error out of if you don't have ex_doc as dependency, and the chances of ex_doc failing is low, so really the main thing that could go wrong is in sending up the docs to the api.

My take for rebar3 hex publish is by default :

1. create the release
2. create the docs
3. publish the release
4. publish the docs

Operation 3 doesn't happen unless 1 and 2 happen successfully. You can override this behavior with the switches mentioned in above though. Naturally, operation 4 doesn't happen if 3 fails, in which case we can tell the user to run rebar3 hex publish --docs or rebar3 hex docs

IMO, this how mix hex should operate too, but that's another story and project :)

I think the issue is dependent on what we decide on in #182. Thoughts?

[starbelly]

Closing this per #185 #210 and #211 . Went a slightly different route with the switches, opted for a --without-docs switch, so by default docs will get published if an edoc provider is configured or a doc directory is found. Thus, the user needs to opt-in to publish without docs. This is more inline with mix hex (i.e., mix hex will publish docs by default if ex_doc is in the project). Though, I feel like we need to adjust the behavior in regards to publishing based on whether docs directory is found, that's still a bit unsafe IMO, but I will open a new issue for that.