Publish does not build the docs

[eproxus]

rebar3 hex publish publishes docs by default, but actually doesn't build the docs before. A separate run of rebar3 hex docs as to be done to actually publish the latest docs.

[starbelly]

@eproxus It looks like @tsloughter did some PRs around this area, is this still an issue for you?

[jfacorro]

Hi 👋 . I am still seeing this behaviour when using rebar3 hex publish. The messages shown are the following:

Be aware, you are publishing to the public Hexpm repository.
Before publishing, please read Hex CoC: https://hex.pm/policies/codeofconduct
Proceed? ("Y")>
Local Password:
===> Published project_name 0.1.0
===> Published docs for project_name 0.1.0

But even though there is a link to documentation in https://hex.pm/packages/project_name, it does not link to any existing content.

[starbelly]

@jfacorro Gotcha. I'll take a look at this as soon as I can to try and suss out what's going on here. Can you tell me which version of rebar3_hex you're using?

[jfacorro]

I'm using the latest available version in hex: 6.9.6.

I've been just looking at the code and the issue seems to be that even though the pulishing of the docs occurs through the call of rebar3_hex_docs:publish/3 from rebar3_hex_publish:publish_package_and_docs/7, there is no check whether the documentation directory exists or not.

I am willing to fix this if we can figure out what we want as the expected behaviour 😄 .

If it was up to me, I would just remove the publishing of documentation that is currently linked in a hackish way to the publish command.

[starbelly]

@jfacorro I think the expectation from most people is when they publish they expect the docs to be published with them and this in line with mix hex. This makes sense, as one of the goals at this point is to provide a mostly standardized experience between the two.

I do agree that the way it's linked together right now is sub-optimal. IMO the two modules should be merged and a switch added to indicate you only want to publish docs (I'd say sub-commands, but sub-commands are tricky to support IMO). Rationale being that the two are highly coupled and publishing the docs when you publish a package is usually what most people want. The old command module should probably be kept around so we don't have to do a new major version yet.

@tsloughter what are your thoughts?

All the above aside, the quickest simplest fix is to check whether we actually generated the docs 😁

[starbelly]

Ahh yeah, another part is coming back to memory now... we don't in fact generate the docs... iirc this is because we don't want to assume the user is strictly using edoc. I wonder if we can support some kind of config on this one, of which there's another related ticket (#57)

[jfacorro]

I really like the idea of a configuration since right now the general behaviour is a little obscure IMHO. The publishing of the docs when using publish uses the hard-coded directory doc. The docs commands has edoc as a dependency which might generate the documentation to a different folder altogether.

Maybe we could rely on an entry in the .app.src that specifies where the documentation is located and only run the publishing if there is a {docs, "some/path"} entry in the .app.src.

My vote goes to the following:

• Remove the edoc dependency of the docs command.
• Support a docs entry in .app.src.
• Attempt to publish the documentation when running publish only if there is a docs entry in the .app.src and the directory specified there exists (show an error/warning otherwise).
• When the docs command is run on its own follow the same behaviour as above (e.g. rely on docs entry and warn/error if dir is not there).

[ferd]

I don't especially like moving more build tool-specific information into .app.src for this, mostly since the docs directory already has to be configured in the rebar.config file for edoc in the common case. Unless hex starts mandating the information to be there (like the license and whatnot) I'm not the biggest fan of migrating it there as a mandatory thing.

But seeing it's you making the comment, I understand that this is a friction point for clojerl which likely does not use edoc, right?

[jfacorro]

😄

But seeing it's you making the comment, I understand that this is a friction point for clojerl which likely does not use edoc, right?

I'm working on generating nice looking documentation for projects in general (rebar3_docs), which does not use the edoc command nor all of the edoc generation mechanism, but does call functions from the edoc application to process the docstrings.

The current idea is that you would run rebar3 docs and that would generate the documentation in a directory, just like edoc. Currently the rebar3_docs plugin does not read the options from the edoc_opts entry in rebar.config but I could modify it so that it does. I've been also thinking that maybe the plugin if included in the project should just replace the {default, edoc} command, but I'm still undecided (input on this is very welcome).

[ferd]

Yeah. The way I'm thinking about it is that we should have an order of priority for doc paths. For example:

• command line is always first (if possibly to specify)
• then the .app file (if we add it)
• then whatever may be specified in rebar.config (probably through edoc_opts)
• then whatever we feel is a sensible default (./docs)

The idea being that as long as we can, the user has nothing to specify, but if they hit a wall, then they can work around it. The problem is generally of figuring out how to let them know they can work around problems, and so far the main solution is "ask someone or go read docs".

[jfacorro]

I like the approach of implementing an order of priority and the one you proposed in the list above looks reasonable to me.

I think the publishing of documentation should still fail if the resolved directory does not exist, though. As opposed to what is happening now, where the publishing "succeeds" but there is no actual documentation.

[ferd]

Agreed. "Docs not published as they couldn't be found in ; build them and run rebar3 hex docs to publish" would be friendly as a way to cope for example.