llvm dev - Apr 2017 - Debugging Docs and llvm.org/docs/

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

> 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

On 7 April 2017 at 19:18, Tanya Lattner <tanyalattner at llvm.org>
wrote:
> 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)
Hum, SUCCESS on 1st of April... suspicious... :)

> 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 :)
Agreed!

--renato

On Fri, Apr 7, 2017 at 1:18 PM, Tanya Lattner <tanyalattner at llvm.org>
wrote:
>
> > On Apr 7, 2017, at 8:09 AM, Renato Golin <renato.golin at
linaro.org>
> wrote:
> ...
>
>
>
>
> > In that sense, this website is somewhat similar to hosting our code on
> > GitHub. It's someone else's problem.
> >
>
>
I have been unable to find out how to change the hostname for my
readthedocs project.  Changing the project name did not change the
hostname, even after pushing new commits.  So https://llvm.readthedocs.org/
still points to my fork of the LLVM github project.  So, I will delete this
llvm readthedocs project unless I hear objections.  If we decide to
continue to evaluate it further, we should probably hook it up to the real
LLVM GH repo.  I can help execute that integration or show someone w/GH
repo permissions how to do it (but it's very straightforward).

Also, I dug in a little deeper on readthedocs details.  Here's more food
for thought regarding this debate of "it's someone else's
problem":

- yes, there is an notification facility regarding failed doc builds.  Both
via email and webhook, multiple entries supported for each.

- yes, there is a way to associate additional domains with the docs.

- readthedocs.org apparently has an advertising supported model *.  In
practice it seems a little rarebut they reserve that right, with some
exceptions (see below).

- The doc build that I magically got working just searched for the conf.py
file and triggered a normal sphinx build from there.  It do not believe it
ran the full LLVM_BUILD_DOCS (which would've included doxygen, right?).

- readthedocs does support building current/trunk separate from tagged
releases.

- other supported features: translations, page redirections (for the sake
of redirecting referrers w/stale URLs, e.g.), subprojects, PDF/EPUB targets
in addition to HTML, Google analytics (provide your own tracking ID).


* here's more details on the advertising (tl;dr please let us run
occasional ads, pay us, or contribute to our open source project as a
volunteer, or none of the above but don't you feel bad now?)


Documentation Advertising
> Read the Docs is an open source project, maintained and operated by
> full-time volunteers. In order to maintain service, we rely on both the
> support of our users, and from sponsor support.
> We will periodically run advertisements on built documentation pages for
> sponsors, however we have strict guidelines on advertisements:
>
>    - We don't give sponsors access to user information
>
>
>    - We only report the number of impressions and number of ad clicks
>
>
>    - We only allow and image and text, no Javascript besides our existing
>    tracking
>
> For more information on our stance on sponsor advertisements, we wrote
> more about our stance on our blog
> <https://blog.readthedocs.com/ads-on-read-the-docs/>.
> Opting out
> If you do not wish to support Read the Docs with use of this ad space, we
> ask that you help support Read the Docs in one of following ways:



-- 
-Brian
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://lists.llvm.org/pipermail/llvm-dev/attachments/20170409/53543409/attachment.html>