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

[Renato Golin via llvm-dev]

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.
* 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.

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 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.

But that seems more involved and problematic (SSH/FTP keys, etc.),
which may defeat our "move to public infrastructure to avoid costs"
trend.

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

cheers,
--renato