Hint on registering generated documentation with DocumentationGeneratorRegistry

[j-fu]

Registering with DocumentationGeneratorRegistry ensures that JuliaHub points to the documentation version hosted on the package repo rather than to a possibly stripped-down version.

See JuliaComputing/JuliaHub-Feedback#161 for a hint that this can be done.

[j-fu]

Also see this discussion on Zulip .

[odow]

I am strongly against adding this. I want JuliaHub to fix this on their end. I don't want the open-source community to have to do work to make their product better.

Right now, JuliaHub is taking content and (poorly) re-mixing it without attribution or identifying that is not a product of the original authors. Forcing open-source users to tell a third-party "stop screwing up my documentation" is not the solution.

[j-fu]

I tend to agree - I just went through these additional actions. They indeed increase the hurdles for package developers. And registration with DocumentationGeneratorRegistry via PR without automated merging etc feels so much different from the deployment services of Documenter, JuliaRegistrator.

With this PR I just want to move the discussion in a constructive way, let's keep this open for this purpose.

[DanielVandH]

I think adding this can be fine just so that people are aware - I doubt most people even know that JuliaHub is doing this. I agree that the perfect solution would be to have JuliaHub stop putting the onus on package developers to fix it, but given that nothing has been happening on that front for a long time now and there has been little communication about it, maybe this is maybe an okay temporary solution.

I guess an argument against that is that it might somehow encourage JuliaHub to delay fixing it for longer.

[mortenpi]

Sorry for the delay. I'm actually a little bit of two minds here (in addition to two hats.. but I'm wearing my JuliaDocs/Documenter open source one right now).

I think JuliaHub is a valid place to host your package's docs. There are packages in General that host their docs on juliahub.com. And so mentioning it on the hosting page as one of several alternatives seems fine to me.

However, that's not really what this is about. This is about warning users about the potential issues and informing them about the opt-out. And I see how that can be useful for Documenter's users. But at the same time, I am also not sure that what third party entities do is the concern of the Documenter open source project.

I guess one way to reconcile that would be to rephrase this in a way that it's mentioning JuliaHub as a hosting alternative, but then also giving the caveats about opt-outs etc. But I'm not sure, and I'm not sure I should be making the call here.

[DanielVandH]

However, that's not really what this is about. This is about warning users about the potential issues and informing them about the opt-out. And I see how that can be useful for Documenter's users. But at the same time, I am also not sure that what third party entities do is the concern of the Documenter open source project.

I don't really understand this. Yes technically it probably shouldn't be a concern as it is a third party, but it is a serious issue to be aware of for those using Documenter. There should be more knowledge about it.
Alternatively I would wish that there was more pressure for it to be actually fixed on the JuliaHub side, but that's optimistic.

Perhaps more attention needs to given to actually addressing JuliaComputing/JuliaHub-Feedback#161.

[j-fu]

I would say the problem is not the hosting at JuliaHub per se, but that the documentation seen on JuliaHub in most cases I have seen is just a very much stripped down version with just the docstrings and the README. As package links e.g. from Zulip now default to JuliaHub, this produces false impressions. What I try to describe here should inform package authors how to fix this situation.

However,

But at the same time, I am also not sure that what third party entities do is the concern of the Documenter open source project.

So yes, this should not be necessary, in particular as it puts an additional burden on the package authors (and most of them probably are not aware of it). It really should be fixed on the JuliaHub side.

[goerz]

I would merge this. I'm not quite sure why this is so controversial, or where

I am strongly against adding this.

Is coming from. Unless it's just the rhetorical prelude to

I want JuliaHub to fix this on their end.

Which I agree with 100%, but I don't see how mentioning JuliaHub in the Documenter documentation and JuliaHub fixing things are mutually exclusive. Is the concern that documenting the workaround would concede that the current behavior shouldn't be fixed? Or, that since it should be fixed in the short term (I'm not holding my breath), documenting the workaround is a waste of time?

I think I've expressed my strong criticism of the JuliaHub documentation in the past. I understand the motivation behind it, but the way it is done is something I consider borderline unethical. (This is not to cast blame on any individual employee of JuliaHub, present company included). For an outsider, it's hard to tell that the "documentation" shown on JuliaHub is not the official documentation of a project. Especially when for a handful of packages it actually is! By default, JuliaHub should be displaying a banner "This is an automatic documentation built by JuliaHub. Please check the project page (URL) for the official documentation. Click here for more information." where the "more information" would link to a page that explains why and how exactly JuliaHub builds the "documentation" that they show, and (very prominently) how to opt out.

In the longer term, I wish JuliaHub would make the system opt-in, not opt-out. Unless somebody opts in, they should not be building any documentation, but only link to the official project documentation. That might not always be trivial to find in an automated way. Maybe we could add a documentation URL as a metadata field in Project.toml and make that field mandatory for packages registered in General. I understand JuliaHub has customers with airgapped system, and the "vendored" documentation is partly for their benefit, but I don't think that this kind of vendoring should be made public.

Anyway. I would also say that JuliaHub is not just some random third party, but a pretty central component of the ecosystem. Likewise, Documenter isn't just a random package, but should be the way to do documentation, and document every aspect of documenting Julia packages. Discussing interactions with third-party systems and the ecosystem as a whole should absolutely be in the scope of Documenter's documentation.

On top of that, this particular piece of information is both obscure for newcomers and a major source of frustration especially for those who put a lot of effort into their documentation. The existence of https://github.com/JuliaDocs/DocumentationGeneratorRegistry is very obscure; making it less obscure is something that JuliaHub should urgently address. Personally, I always want to opt out of the JuliaHub-hosted documentation, and, even knowing that there is some repository where I can opt out, I've found it very hard to remember or to find that repository. I've had to actively search for it, and probably had to ask on Slack a few times.

In conclusion, I think mentioning and explaining JuliaHub as this PR does is a great idea, and linking to https://github.com/JuliaDocs/DocumentationGeneratorRegistry is a pragmatic and helpful approach, until JuliaHub makes some fixes. There doesn't seem to be much, if any, momentum at JuliaHub on that front, so documenting the workaround seems worthwhile to me.

[odow]

I'm not quite sure why this is so controversial, or where
Is coming from. Unless it's just the rhetorical prelude to

Yes, all of this.

But at the same time, I am also not sure that what third party entities do is the concern of the Documenter open source project.

Also this.

[mortenpi]

In light of JuliaComputing/JuliaHub-Feedback#161 (comment), let's hold off on this for a few more weeks, until the changes have been deployed, and then figure out if/how we want to have this in the docs here.