Re: [lldb-dev] [RFC] Using Sphinx to generate documentation

[Stefan Gränitz via lldb-dev]

Hey Jonas that looks great! And what a nice way to do the review.

Two of the pages from "RESOURCES" are in the new docs now: Testing LLDB and The 
SB API Coding Rules
Will they be removed from the root page and/or do the others follow?

Added a few notes on escape characters to the review.

> The biggest issue is that the GDB to LLDB command map is totally unreadable 
> with the RST generated table. I spent a little time tweaking the CSS, but 
> this needs some attention. Worst case we'll have to have an HTML table here. 

GDB to LLDB map is one of  the most viewed pages in the docs right? I had a 
look and got the below result with a few CSS tweaks in the layout "debugger":

p, blockquote { margin-top: 0px; margin-bottom: 0px; }
tr.row-even { background: #eee; }
tr.row-odd td { font-family: monospace; padding-bottom: 15px; }
table.docutils { width: 100%; }

The last one sets full width on all tables. About columns having 
content-specific width, I am not sure. Might be interesting to see with a 50/50 
setting in all 's.
Maybe we could also get rid of the column headers? The prompts say it all :)




> On 8. Jan 2019, at 19:12, Jonas Devlieghere  wrote:
> 
> For those interested, I've uploaded the latest version of the generated HTML:
> 
> https://jonasdevlieghere.com/static/lldb/ 
> 
> 
> I'd have to double check but I think that almost everything was ported over. 
> The biggest issue is that the GDB to LLDB command map is totally unreadable 
> with the RST generated table. I spent a little time tweaking the CSS, but 
> this needs some attention. Worst case we'll have to have an HTML table here. 
> 
> Theme-wise I went with the one used by clang. I think it's the most readable 
> and I personally really like the local ToC. The disadvantage is that it 
> doesn't have a sidebar, so you have to navigate back to "contents" in the top 
> right corner.
> 
> The alternative is the LLVM theme where we can have Sphinx generate the 
> global ToC in the sidebar. When I tried this it was missing the section names 
> (e.g. "Goals & Status" as seen on the main page).  Another issue is that the 
> local ToC gets totally lost beneath it because everything doesn't fit on the 
> screen. Once I figure out how/if we can include the section names I'll 
> generate the site with the LLVM theme so people can compare and give their 
> opinion.
> 
> Cheers,
> Jonas
> 
> On Tue, Jan 8, 2019 at 9:31 AM Jonas Devlieghere  > wrote:
> 
> 
> On Tue, Jan 8, 2019 at 8:52 AM Stefan Gränitz via lldb-dev 
> mailto:lldb-dev@lists.llvm.org>> wrote:
> Hi Jonas, I think this is a great effort. Thanks!
> 
> My current reviews do some small updates on the build page. Hope this doesn't 
> get in conflict with your work?
> 
> Thanks for the heads up Stefan. This should be fine, I'll copy over your 
> change in the rst files. 
> 
> 
> Best
> Stefan
> 
>> On 6. Dec 2018, at 18:02, Jonas Devlieghere via lldb-dev 
>> mailto:lldb-dev@lists.llvm.org>> wrote:
>> 
>> Hi everyone,
>> 
>> The current LLDB website is written in HTML which is hard to maintain. We 
>> have quite a bit of HTML code checked in which can make it hard to 
>> differentiate between documentation written by us and documentation 
>> generated by a tool. Furthermore I think text/RST files provide a lower 
>> barrier for new or casual contributors to fix or update.
>> 
>> In line with the other LLVM projects I propose generating the documentation 
>> with Sphix. I created a patch (https://reviews.llvm.org/D55376 
>> ) that adds a new target docs-lldb-html 
>> when -DLLVM_ENABLE_SPHINX:BOOL is enabled. I've ported over some pages to 
>> give an idea of what this would look like in-tree. Before continuing with 
>> this rather tedious work I'd like to get feedback form the community.
>> 
>> Initially I started with the theme used by Clang because it's a default 
>> theme and doesn't require configuration. If we want to keep the sidebar we 
>> could use the one used by LLD.
>> 
>> Please let me know what you think.
>> 
>> Thanks,
>> Jonas
>> ___
>> lldb-dev mailing list
>> lldb-dev@lists.llvm.org 
>> http://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-dev 
>> 
> 
> ___
> lldb-dev mailing list
> lldb-dev@lists.llvm.org 
> http://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-dev 
> 

___
lldb-dev mailing list
lldb-dev@lists.llvm.org
http://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-dev

Re: [lldb-dev] [RFC] Using Sphinx to generate documentation

[Jonas Devlieghere via lldb-dev]

For those interested, I've uploaded the latest version of the generated
HTML:

https://jonasdevlieghere.com/static/lldb/

I'd have to double check but I think that almost everything was ported
over. The biggest issue is that the GDB to LLDB command map is totally
unreadable with the RST generated table. I spent a little time tweaking the
CSS, but this needs some attention. Worst case we'll have to have an HTML
table here.

Theme-wise I went with the one used by clang. I think it's the most
readable and I personally really like the local ToC. The disadvantage is
that it doesn't have a sidebar, so you have to navigate back to "contents"
in the top right corner.

The alternative is the LLVM theme where we can have Sphinx generate the
global ToC in the sidebar. When I tried this it was missing the section
names (e.g. "Goals & Status" as seen on the main page).  Another issue is
that the local ToC gets totally lost beneath it because everything doesn't
fit on the screen. Once I figure out how/if we can include the section
names I'll generate the site with the LLVM theme so people can compare and
give their opinion.

Cheers,
Jonas

On Tue, Jan 8, 2019 at 9:31 AM Jonas Devlieghere 
wrote:

>
>
> On Tue, Jan 8, 2019 at 8:52 AM Stefan Gränitz via lldb-dev <
> lldb-dev@lists.llvm.org> wrote:
>
>> Hi Jonas, I think this is a great effort. Thanks!
>>
>> My current reviews do some small updates on the build page. Hope this
>> doesn't get in conflict with your work?
>>
>
> Thanks for the heads up Stefan. This should be fine, I'll copy over your
> change in the rst files.
>
>
>> Best
>> Stefan
>>
>> On 6. Dec 2018, at 18:02, Jonas Devlieghere via lldb-dev <
>> lldb-dev@lists.llvm.org> wrote:
>>
>> Hi everyone,
>>
>> The current LLDB website is written in HTML which is hard to maintain. We
>> have quite a bit of HTML code checked in which can make it hard to
>> differentiate between documentation written by us and documentation
>> generated by a tool. Furthermore I think text/RST files provide a lower
>> barrier for new or casual contributors to fix or update.
>>
>> In line with the other LLVM projects I propose generating the
>> documentation with Sphix. I created a patch (
>> https://reviews.llvm.org/D55376) that adds a new target docs-lldb-html
>> when -DLLVM_ENABLE_SPHINX:BOOL is enabled. I've ported over some pages to
>> give an idea of what this would look like in-tree. Before continuing with
>> this rather tedious work I'd like to get feedback form the community.
>>
>> Initially I started with the theme used by Clang because it's a default
>> theme and doesn't require configuration. If we want to keep the sidebar we
>> could use the one used by LLD.
>>
>> Please let me know what you think.
>>
>> Thanks,
>> Jonas
>> ___
>> lldb-dev mailing list
>> lldb-dev@lists.llvm.org
>> http://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-dev
>>
>>
>> ___
>> lldb-dev mailing list
>> lldb-dev@lists.llvm.org
>> http://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-dev
>>
>
___
lldb-dev mailing list
lldb-dev@lists.llvm.org
http://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-dev

Re: [lldb-dev] [RFC] Using Sphinx to generate documentation

[Stefan Gränitz via lldb-dev]

Hi Jonas, I think this is a great effort. Thanks!

My current reviews do some small updates on the build page. Hope this doesn't 
get in conflict with your work?

Best
Stefan

> On 6. Dec 2018, at 18:02, Jonas Devlieghere via lldb-dev 
>  wrote:
> 
> Hi everyone,
> 
> The current LLDB website is written in HTML which is hard to maintain. We 
> have quite a bit of HTML code checked in which can make it hard to 
> differentiate between documentation written by us and documentation generated 
> by a tool. Furthermore I think text/RST files provide a lower barrier for new 
> or casual contributors to fix or update.
> 
> In line with the other LLVM projects I propose generating the documentation 
> with Sphix. I created a patch (https://reviews.llvm.org/D55376 
> ) that adds a new target docs-lldb-html when 
> -DLLVM_ENABLE_SPHINX:BOOL is enabled. I've ported over some pages to give an 
> idea of what this would look like in-tree. Before continuing with this rather 
> tedious work I'd like to get feedback form the community.
> 
> Initially I started with the theme used by Clang because it's a default theme 
> and doesn't require configuration. If we want to keep the sidebar we could 
> use the one used by LLD.
> 
> Please let me know what you think.
> 
> Thanks,
> Jonas
> ___
> lldb-dev mailing list
> lldb-dev@lists.llvm.org
> http://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-dev

___
lldb-dev mailing list
lldb-dev@lists.llvm.org
http://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-dev

Re: [lldb-dev] [RFC] Using Sphinx to generate documentation

[Jonas Devlieghere via lldb-dev]

> On Dec 7, 2018, at 4:37 AM, Bruce Mitchener via lldb-dev 
>  wrote:
> 
>> On Fri, Dec 7, 2018 at 6:11 PM Raphael Isemann via lldb-dev 
>>  wrote:
>> I think if we want to actually lower the entry barrier for
>> contributing/fixing things on the website, then the server should do
>> this. From what I know the other LLVM projects also generate the HTML
>> on the server (at least I've never seen anyone commit generated HTML
>> files), so this hopefully shouldn't be too complicated.

Yes, I definitely want to generate it. It should be straightforward to add a 
build bot that does this. I’ll see what is needed for this while I continue 
porting the other pages.

I’d like to have the doxygen and python documentation generated as well. The 
one that’s currently hosted on llvm.org is several years old, last time I 
checked. 

> Agree. Also, there's enough differences between the generated HTML for 
> various versions of the tools that having it happen on the server would be 
> good. 

I’d have to double check how llvm 

>  
>> I think in general this approach is really nice. Thanks a lot for the
>> work @Jonas!
> 
> Indeed!

My pleasure! I’m happy to see the positive reception here.

> 
>  - Bruce
> 
> ___
> lldb-dev mailing list
> lldb-dev@lists.llvm.org
> http://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-dev
___
lldb-dev mailing list
lldb-dev@lists.llvm.org
http://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-dev

Re: [lldb-dev] [RFC] Using Sphinx to generate documentation

[Raphael Isemann via lldb-dev]

I think if we want to actually lower the entry barrier for
contributing/fixing things on the website, then the server should do
this. From what I know the other LLVM projects also generate the HTML
on the server (at least I've never seen anyone commit generated HTML
files), so this hopefully shouldn't be too complicated.

I think in general this approach is really nice. Thanks a lot for the
work @Jonas!

- Raphael


Am Fr., 7. Dez. 2018 um 09:06 Uhr schrieb Pavel Labath via lldb-dev
:
>
> On 06/12/2018 18:02, Jonas Devlieghere via lldb-dev wrote:
> > Hi everyone,
> >
> > The current LLDB website is written in HTML which is hard to maintain.
> > We have quite a bit of HTML code checked in which can make it hard to
> > differentiate between documentation written by us and documentation
> > generated by a tool. Furthermore I think text/RST files provide a lower
> > barrier for new or casual contributors to fix or update.
> >
> > In line with the other LLVM projects I propose generating the
> > documentation with Sphix. I created a patch
> > (https://reviews.llvm.org/D55376) that adds a new target docs-lldb-html
> > when -DLLVM_ENABLE_SPHINX:BOOL is enabled. I've ported over some pages
> > to give an idea of what this would look like in-tree. Before continuing
> > with this rather tedious work I'd like to get feedback form the community.
> >
> > Initially I started with the theme used by Clang because it's a default
> > theme and doesn't require configuration. If we want to keep the sidebar
> > we could use the one used by LLD.
> >
> > Please let me know what you think.
> >
> > Thanks,
> > Jonas
> >
>
> Woohoo!
>
> Just to be clear, is the idea to still check in the resulting html files
> to remain compatible with how http://lldb.llvm.org (I have no idea who
> maintains that) works, or do you want to change that as well (e.g., by
> having the server generate the html files locally).
>
> pl
> ___
> lldb-dev mailing list
> lldb-dev@lists.llvm.org
> http://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-dev
___
lldb-dev mailing list
lldb-dev@lists.llvm.org
http://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-dev

Re: [lldb-dev] [RFC] Using Sphinx to generate documentation

[Pavel Labath via lldb-dev]

On 06/12/2018 18:02, Jonas Devlieghere via lldb-dev wrote:

Hi everyone,

The current LLDB website is written in HTML which is hard to maintain. 
We have quite a bit of HTML code checked in which can make it hard to 
differentiate between documentation written by us and documentation 
generated by a tool. Furthermore I think text/RST files provide a lower 
barrier for new or casual contributors to fix or update.


In line with the other LLVM projects I propose generating the 
documentation with Sphix. I created a patch 
(https://reviews.llvm.org/D55376) that adds a new target docs-lldb-html 
when -DLLVM_ENABLE_SPHINX:BOOL is enabled. I've ported over some pages 
to give an idea of what this would look like in-tree. Before continuing 
with this rather tedious work I'd like to get feedback form the community.


Initially I started with the theme used by Clang because it's a default 
theme and doesn't require configuration. If we want to keep the sidebar 
we could use the one used by LLD.


Please let me know what you think.

Thanks,
Jonas



Woohoo!

Just to be clear, is the idea to still check in the resulting html files 
to remain compatible with how http://lldb.llvm.org (I have no idea who 
maintains that) works, or do you want to change that as well (e.g., by 
having the server generate the html files locally).


pl
___
lldb-dev mailing list
lldb-dev@lists.llvm.org
http://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-dev

Re: [lldb-dev] [RFC] Using Sphinx to generate documentation

[Bruce Mitchener via lldb-dev]

I like this a lot!

I commented on the patch since I didn't see this thread at the time, but
it'd be interesting to perhaps replace Epydoc with Sphinx as well.

 - Bruce


On Fri, Dec 7, 2018 at 12:02 AM Jonas Devlieghere via lldb-dev <
lldb-dev@lists.llvm.org> wrote:

> Hi everyone,
>
> The current LLDB website is written in HTML which is hard to maintain. We
> have quite a bit of HTML code checked in which can make it hard to
> differentiate between documentation written by us and documentation
> generated by a tool. Furthermore I think text/RST files provide a lower
> barrier for new or casual contributors to fix or update.
>
> In line with the other LLVM projects I propose generating the
> documentation with Sphix. I created a patch (
> https://reviews.llvm.org/D55376) that adds a new target docs-lldb-html
> when -DLLVM_ENABLE_SPHINX:BOOL is enabled. I've ported over some pages to
> give an idea of what this would look like in-tree. Before continuing with
> this rather tedious work I'd like to get feedback form the community.
>
> Initially I started with the theme used by Clang because it's a default
> theme and doesn't require configuration. If we want to keep the sidebar we
> could use the one used by LLD.
>
> Please let me know what you think.
>
> Thanks,
> Jonas
> ___
> lldb-dev mailing list
> lldb-dev@lists.llvm.org
> http://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-dev
>
___
lldb-dev mailing list
lldb-dev@lists.llvm.org
http://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-dev

[lldb-dev] [RFC] Using Sphinx to generate documentation

[Jonas Devlieghere via lldb-dev]

Hi everyone,

The current LLDB website is written in HTML which is hard to maintain. We have 
quite a bit of HTML code checked in which can make it hard to differentiate 
between documentation written by us and documentation generated by a tool. 
Furthermore I think text/RST files provide a lower barrier for new or casual 
contributors to fix or update.

In line with the other LLVM projects I propose generating the documentation 
with Sphix. I created a patch (https://reviews.llvm.org/D55376 
) that adds a new target docs-lldb-html when 
-DLLVM_ENABLE_SPHINX:BOOL is enabled. I've ported over some pages to give an 
idea of what this would look like in-tree. Before continuing with this rather 
tedious work I'd like to get feedback form the community.

Initially I started with the theme used by Clang because it's a default theme 
and doesn't require configuration. If we want to keep the sidebar we could use 
the one used by LLD.

Please let me know what you think.

Thanks,
Jonas
___
lldb-dev mailing list
lldb-dev@lists.llvm.org
http://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-dev