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

That was easy! :-)

The ones I looked are fine, too. Thanks!

I think we could get them under docs.llvm.org or something, by just
pointing our dns somewhere?

Cheers,
Renato

On 7 Apr 2017 02:10, "Brian Cain" <brian.cain at gmail.com>
wrote:
>
>
> On Thu, Apr 6, 2017 at 6:17 PM, Tanya Lattner via llvm-dev <
> llvm-dev at lists.llvm.org> wrote:
>
>>
>> > On Apr 6, 2017, at 2:52 AM, Renato Golin <renato.golin at
linaro.org>
>> wrote:
>> >
>> > On 6 April 2017 at 05:49, Dean Michael Berris <dean.berris at
gmail.com>
>> wrote:
>> >> I'll have a look if I can untangle that.
>> >>
>> >> Thanks Renato!
>> >
>> > Well, that didn't last long. Now I remember why last time I
fixed
>> > hundreds of warnings on the docs directly instead of fixing the
>> > server...
>> >
>> >
>> >> Has anybody looked into potentially getting the LLVM docs
hosted on
>> >> readthedocs.org and automatically built from the LLVM Git
mirror (or
>> through
>> >> Subversion post-commit hooks)? Since we're already using
Sphinx, this
>> seems
>> >> like a low-cost, low-interference way of hosting the generated
>> >> documentation.
>> >
>> > This is actually a very good idea. I'll let Tanya and Anton
further
>> > comment on that from a foundation's point of view.
>>
>> The docs are built via SVN post-commit hook, but thats not the bigger
>> issue in my opinion. I don’t know enough about readthedocs.org but if
>> someone has a lot of experience.. perhaps they could summarize pros and
>> cons of using it?
>>
>> I’m not opposed to change just need to understand it. I’m actually
going
>> to be handing off most of this stuff as soon as I can write the email
to
>> the list (sorry its Spring Break here in the US so my time is limited
this
>> week). I have someone who is going to help with sys admin on llvm.org
>> and head things up in that area but ideally its a team of people.
>>
>>
> I don't know the answers re: pros/cons, I've never built anything
with
> readthedocs before.  But I was curious about how hard it is to setup so I
> gave it a whirl.  The answer appears to be: not very hard at all.  I added
> a two-line YAML config file but from the docs I read it seems like it was a
> superfluous step.  Most of the work was clicking a handful of buttons on
> github and readthedocs' websites.
>
> https://llvm.readthedocs.io/en/latest/
>
>
> Apologies for squatting on the project name, I thought the url would be
> qualified by my username.  I'll see how I can get it changed to move
out of
> the way for the LLVM project.
>
> I did a spot check of several pages and couldn't find obvious
> missing/invalid parts of the docs.  This is just llvm and not clang nor any
> other project, though.
>
> https://llvm.readthedocs.io/en/latest/GoldPlugin.html
>
> https://llvm.readthedocs.io/en/latest/WritingAnLLVMPass.html
>
> https://llvm.readthedocs.io/en/latest/HowToCrossCompileLLVM.html
>
>
> Even search works:
>
> https://llvm.readthedocs.io/en/latest/search.html?q=bitcode
>
>
> -Brian
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://lists.llvm.org/pipermail/llvm-dev/attachments/20170407/ad1071e1/attachment.html>

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?

-Tanya
> On Apr 7, 2017, at 2:08 AM, Renato Golin <renato.golin at linaro.org>
wrote:
> 
> That was easy! :-)
> 
> The ones I looked are fine, too. Thanks! 
> 
> I think we could get them under docs.llvm.org or something, by just
pointing our dns somewhere?
> 
> Cheers, 
> Renato 
> 
>> On 7 Apr 2017 02:10, "Brian Cain" <brian.cain at
gmail.com> wrote:
>> 
>> 
>>> On Thu, Apr 6, 2017 at 6:17 PM, Tanya Lattner via llvm-dev
<llvm-dev at lists.llvm.org> wrote:
>>> 
>>> > On Apr 6, 2017, at 2:52 AM, Renato Golin <renato.golin at
linaro.org> wrote:
>>> >
>>> > On 6 April 2017 at 05:49, Dean Michael Berris <dean.berris
at gmail.com> wrote:
>>> >> I'll have a look if I can untangle that.
>>> >>
>>> >> Thanks Renato!
>>> >
>>> > Well, that didn't last long. Now I remember why last time
I fixed
>>> > hundreds of warnings on the docs directly instead of fixing
the
>>> > server...
>>> >
>>> >
>>> >> Has anybody looked into potentially getting the LLVM docs
hosted on
>>> >> readthedocs.org and automatically built from the LLVM Git
mirror (or through
>>> >> Subversion post-commit hooks)? Since we're already
using Sphinx, this seems
>>> >> like a low-cost, low-interference way of hosting the
generated
>>> >> documentation.
>>> >
>>> > This is actually a very good idea. I'll let Tanya and
Anton further
>>> > comment on that from a foundation's point of view.
>>> 
>>> The docs are built via SVN post-commit hook, but thats not the
bigger issue in my opinion. I don’t know enough about readthedocs.org but if
someone has a lot of experience.. perhaps they could summarize pros and cons of
using it?
>>> 
>>> I’m not opposed to change just need to understand it. I’m actually
going to be handing off most of this stuff as soon as I can write the email to
the list (sorry its Spring Break here in the US so my time is limited this
week). I have someone who is going to help with sys admin on llvm.org and head
things up in that area but ideally its a team of people.
>>> 
>> 
>> I don't know the answers re: pros/cons, I've never built
anything with readthedocs before.  But I was curious about how hard it is to
setup so I gave it a whirl.  The answer appears to be: not very hard at all.  I
added a two-line YAML config file but from the docs I read it seems like it was
a superfluous step.  Most of the work was clicking a handful of buttons on
github and readthedocs' websites.
>> 
>> https://llvm.readthedocs.io/en/latest/
>> 
>> Apologies for squatting on the project name, I thought the url would be
qualified by my username.  I'll see how I can get it changed to move out of
the way for the LLVM project.
>> 
>> I did a spot check of several pages and couldn't find obvious
missing/invalid parts of the docs.  This is just llvm and not clang nor any
other project, though.
>> 
>> https://llvm.readthedocs.io/en/latest/GoldPlugin.html
>> https://llvm.readthedocs.io/en/latest/WritingAnLLVMPass.html
>> https://llvm.readthedocs.io/en/latest/HowToCrossCompileLLVM.html
>> 
>> Even search works:
>> https://llvm.readthedocs.io/en/latest/search.html?q=bitcode
>> 
>> -Brian 
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://lists.llvm.org/pipermail/llvm-dev/attachments/20170407/9d019da7/attachment-0001.html>

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