[llvm-dev] Debugging Docs and llvm.org/docs/

[Tanya Lattner via llvm-dev]

> On Apr 7, 2017, at 8:09 AM, Renato Golin <renato.golin at linaro.org> wrote:
> 
> On 7 April 2017 at 15:50, Tanya Lattner <tanyalattner at llvm.org> wrote:
>> So, building the docs isn't the issue I feel is the problem. The script we
>> have works totally fine. The problem is people breaking the docs.
>> 
>> So how is this better?
> 
> I don't know enough about the website, but there are other problems in
> our infrastructure:
> 
> * We need to manually update Sphinx. People out there can have much
> newer versions, which accept newer syntax, and it doesn't break on
> their side, but it breaks on the server.

Upgrading is generally simple. I think the bigger issue is being out of sync with whatever the person is testing. You have this problem with CMake and other tools and usually specify a minimum version to ensure features work. I assume that this is done with Sphinx? 

If anyone changes that, they would need to notify the administrators of the WWW server or better yet, they could upgrade this themselves (code owner only or trusted one). Sphinx upgrades don’t usually require a reboot or apache restart so it would be minimal disruption.

> * We have buildbots that validate the docs, but again, it's a
> completely separate machine, with a different version still (at least
> potentially).
> * The buildbot doesn't push its builds to the server, nor it's
> guaranteed to have the same version as the actual builder, so
> maintenance is hard.
> * The server process doesn't warn people when it breaks. At least not
> developers.

True. I think having a buildbot for testing docs would be ideal. It doesn’t need to be the same machine as the WWW server and I would prefer separate. But it needs to be using the same Sphinx version which we can control. I have modified the scripts to give status to a mailing list (on new server, http://lists.llvm.org/pipermail/www-scripts/2017-April/002264.html) but modifying them to directly alert the person who broke it would be re-inventing the wheel.. so a buildbot would be better for that probably. But, it could be easy to add to the script maybe.

> 
> What does this website fix?
> 
> * Can it report failed builds? Or at least show on a public webpage
> what's the problem?
> * Can we email people when the docs are broken? At least a generic
> list like llvm-admin?
> * How often Sphinx is updated on the website? Is it always the most
> modern version?

I think this last issue is still the biggest. We need this to be in sync with what developers do. I need to go look at the website to find out their policy. 

Having a few moments to think about this (sorry its spring break week here, family obligations), there are other docs on the WWW server that use LLVM/CLang tools and sphinx that could not be offloaded (attributes generation). Decoupling them from the build might be more trouble than its worth. 

But these are just things that need to be thought through more.

> 
> I think those three points are true, but I don't know for sure. If
> they are, at least some of the problems are fixed.
> 
> Another solution is to make the buildbot push the docs somewhere, so
> at least we have a consistent process, and whatever happens on the
> public bot, happens on the docs.

Possibly an option. Getting a buildbot for this would be easy and not too expensive from my perspective. We could possibly have other uses for it.
> 
> But that seems more involved and problematic (SSH/FTP keys, etc.),
> which may defeat our "move to public infrastructure to avoid costs"
> trend.

Well, I am more of the opinion is that we do whats best for the project and not what is free or cheap. So its good to evaluate the options. Its not that expensive for us to host the docs and website, but I would like to solve the Sphinx version out of sync problem. But if this website turns out to be the best route, then thats ok too. Or maybe a buildbot is the best idea given that I have docs that rely on Clang/LLVM tools. Lets keep talking about it :)

-Tanya

> 
> In that sense, this website is somewhat similar to hosting our code on
> GitHub. It's someone else's problem.
> 
> cheers,
> --renato