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

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

-Tanya
> 
> cheers,
> --renato

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/20170406/a510ebdc/attachment.html>

> On 7 Apr 2017, at 11:10, Brian Cain via llvm-dev <llvm-dev at
lists.llvm.org> wrote:
> 
> 
> 
> On Thu, Apr 6, 2017 at 6:17 PM, Tanya Lattner via llvm-dev <llvm-dev at
lists.llvm.org <mailto:llvm-dev at lists.llvm.org>> wrote:
> 
> > On Apr 6, 2017, at 2:52 AM, Renato Golin <renato.golin at
linaro.org <mailto:renato.golin at linaro.org>> wrote:
> >
> > On 6 April 2017 at 05:49, Dean Michael Berris <dean.berris at
gmail.com <mailto: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 <http://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
<http://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 <http://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/
<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/GoldPlugin.html>
> https://llvm.readthedocs.io/en/latest/WritingAnLLVMPass.html
<https://llvm.readthedocs.io/en/latest/WritingAnLLVMPass.html>
> https://llvm.readthedocs.io/en/latest/HowToCrossCompileLLVM.html
<https://llvm.readthedocs.io/en/latest/HowToCrossCompileLLVM.html>
> 
> Even search works:
> https://llvm.readthedocs.io/en/latest/search.html?q=bitcode
<https://llvm.readthedocs.io/en/latest/search.html?q=bitcode>
> 
You beat me to it Brian, thank you for giving this a go!

/me just happy to see https://llvm.readthedocs.io/en/latest/XRayExample.html
<https://llvm.readthedocs.io/en/latest/XRayExample.html> working out just
fine. :)

-- Dean

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

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>