[llvm-dev] Introduction and Question about Docs

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
12 messages Options
Reply | Threaded
Open this post in threaded view
|

[llvm-dev] Introduction and Question about Docs

Rajesh S R via llvm-dev

Hi everyone. My name is DeForest Richards. I’m the technical writer who was selected to work on the LLVM project as part of the Google Season of Docs program. I’ll be helping to restructure the documentation page(s) to make it easier for new and existing users to navigate the LLVM docs. 


I’m currently reviewing the existing docs, so you’ll probably see me posting questions over the next several weeks. That said, I do have a couple of quick questions that I wanted to ask right now…


  1. I noticed that the LLVM Docs currently use Sphinx 1.7.6, which is an older version. (I believe 2.x is the latest version.) Is this intentional? Updating to the latest version of Sphinx is probably low on my list of priorities, but I was just curious if there was a specific reason for keeping the docs at the older version.
  1. Back in 2012, there was a commit that removed the sidebar from the Docs page. Does anyone know/remember why this was done? I checked the commit message but it’s fairly short and doesn’t provide much context.

_______________________________________________
LLVM Developers mailing list
[hidden email]
https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev
Reply | Threaded
Open this post in threaded view
|

Re: [llvm-dev] Introduction and Question about Docs

Rajesh S R via llvm-dev
I don't have answers to your questions, but I wanted to say that I'm excited to hear that someone is looking at documentation!

On Mon, Aug 19, 2019 at 12:38 PM via llvm-dev <[hidden email]> wrote:

Hi everyone. My name is DeForest Richards. I’m the technical writer who was selected to work on the LLVM project as part of the Google Season of Docs program. I’ll be helping to restructure the documentation page(s) to make it easier for new and existing users to navigate the LLVM docs. 


I’m currently reviewing the existing docs, so you’ll probably see me posting questions over the next several weeks. That said, I do have a couple of quick questions that I wanted to ask right now…


  1. I noticed that the LLVM Docs currently use Sphinx 1.7.6, which is an older version. (I believe 2.x is the latest version.) Is this intentional? Updating to the latest version of Sphinx is probably low on my list of priorities, but I was just curious if there was a specific reason for keeping the docs at the older version.
  1. Back in 2012, there was a commit that removed the sidebar from the Docs page. Does anyone know/remember why this was done? I checked the commit message but it’s fairly short and doesn’t provide much context.
_______________________________________________
LLVM Developers mailing list
[hidden email]
https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev

_______________________________________________
LLVM Developers mailing list
[hidden email]
https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev
Reply | Threaded
Open this post in threaded view
|

Re: [llvm-dev] Introduction and Question about Docs

Rajesh S R via llvm-dev
Thanks! I'm looking forward to helping out with the docs.

On Mon, Aug 19, 2019, 2:22 PM Reid Kleckner <[hidden email]> wrote:
I don't have answers to your questions, but I wanted to say that I'm excited to hear that someone is looking at documentation!

On Mon, Aug 19, 2019 at 12:38 PM via llvm-dev <[hidden email]> wrote:

Hi everyone. My name is DeForest Richards. I’m the technical writer who was selected to work on the LLVM project as part of the Google Season of Docs program. I’ll be helping to restructure the documentation page(s) to make it easier for new and existing users to navigate the LLVM docs. 


I’m currently reviewing the existing docs, so you’ll probably see me posting questions over the next several weeks. That said, I do have a couple of quick questions that I wanted to ask right now…


  1. I noticed that the LLVM Docs currently use Sphinx 1.7.6, which is an older version. (I believe 2.x is the latest version.) Is this intentional? Updating to the latest version of Sphinx is probably low on my list of priorities, but I was just curious if there was a specific reason for keeping the docs at the older version.
  1. Back in 2012, there was a commit that removed the sidebar from the Docs page. Does anyone know/remember why this was done? I checked the commit message but it’s fairly short and doesn’t provide much context.
_______________________________________________
LLVM Developers mailing list
[hidden email]
https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev

_______________________________________________
LLVM Developers mailing list
[hidden email]
https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev
Reply | Threaded
Open this post in threaded view
|

Re: [llvm-dev] Introduction and Question about Docs

Rajesh S R via llvm-dev
In reply to this post by Rajesh S R via llvm-dev
On Mon, Aug 19, 2019 at 12:38 PM via llvm-dev <[hidden email]> wrote:

Hi everyone. My name is DeForest Richards. I’m the technical writer who was selected to work on the LLVM project as part of the Google Season of Docs program. I’ll be helping to restructure the documentation page(s) to make it easier for new and existing users to navigate the LLVM docs. 


I’m currently reviewing the existing docs, so you’ll probably see me posting questions over the next several weeks. That said, I do have a couple of quick questions that I wanted to ask right now…


  1. I noticed that the LLVM Docs currently use Sphinx 1.7.6, which is an older version. (I believe 2.x is the latest version.) Is this intentional? Updating to the latest version of Sphinx is probably low on my list of priorities, but I was just curious if there was a specific reason for keeping the docs at the older version.

There's no specific reason for this.  We setup Sphinx a while ago and only upgraded once to get markdown support (which is now the preferred format for new docs).  The only constraint on upgrading to 2.x would be is it available on our minimum supported platform, or are we willing to have a higher minimum for generating the docs.
 
  1. Back in 2012, there was a commit that removed the sidebar from the Docs page. Does anyone know/remember why this was done? I checked the commit message but it’s fairly short and doesn’t provide much context.

Who committed it?

- Michael Spencer


_______________________________________________
LLVM Developers mailing list
[hidden email]
https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev
Reply | Threaded
Open this post in threaded view
|

Re: [llvm-dev] Introduction and Question about Docs

Rajesh S R via llvm-dev
On Tue, Aug 20, 2019 at 9:25 PM Michael Spencer via llvm-dev
<[hidden email]> wrote:

>
> On Mon, Aug 19, 2019 at 12:38 PM via llvm-dev <[hidden email]> wrote:
>>
>> Hi everyone. My name is DeForest Richards. I’m the technical writer who was selected to work on the LLVM project as part of the Google Season of Docs program. I’ll be helping to restructure the documentation page(s) to make it easier for new and existing users to navigate the LLVM docs.
>>
>>
>> I’m currently reviewing the existing docs, so you’ll probably see me posting questions over the next several weeks. That said, I do have a couple of quick questions that I wanted to ask right now…
>>
>>
>> I noticed that the LLVM Docs currently use Sphinx 1.7.6, which is an older version. (I believe 2.x is the latest version.) Is this intentional? Updating to the latest version of Sphinx is probably low on my list of priorities, but I was just curious if there was a specific reason for keeping the docs at the older version.
>
>
> There's no specific reason for this.  We setup Sphinx a while ago and only upgraded once to get markdown support (which is now the preferred format for new docs).  The only constraint on upgrading to 2.x would be is it available on our minimum supported platform, or are we willing to have a higher minimum for generating the docs.
There recently was a disscussion about this in phabricator (i think? i
can't seem to find it right now).
That version is way too new, it's not even in debian sid; enforcing it
would be limiting.

>>
>> Back in 2012, there was a commit that removed the sidebar from the Docs page. Does anyone know/remember why this was done? I checked the commit message but it’s fairly short and doesn’t provide much context.
>
>
> Who committed it?
>
> - Michael Spencer
Roman

> _______________________________________________
> LLVM Developers mailing list
> [hidden email]
> https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev
_______________________________________________
LLVM Developers mailing list
[hidden email]
https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev
Reply | Threaded
Open this post in threaded view
|

Re: [llvm-dev] Introduction and Question about Docs

Rajesh S R via llvm-dev


On Tue, Aug 20, 2019 at 12:36 PM Roman Lebedev <[hidden email]> wrote:
On Tue, Aug 20, 2019 at 9:25 PM Michael Spencer via llvm-dev
<[hidden email]> wrote:
>
> On Mon, Aug 19, 2019 at 12:38 PM via llvm-dev <[hidden email]> wrote:
>>
>> Hi everyone. My name is DeForest Richards. I’m the technical writer who was selected to work on the LLVM project as part of the Google Season of Docs program. I’ll be helping to restructure the documentation page(s) to make it easier for new and existing users to navigate the LLVM docs.
>>
>>
>> I’m currently reviewing the existing docs, so you’ll probably see me posting questions over the next several weeks. That said, I do have a couple of quick questions that I wanted to ask right now…
>>
>>
>> I noticed that the LLVM Docs currently use Sphinx 1.7.6, which is an older version. (I believe 2.x is the latest version.) Is this intentional? Updating to the latest version of Sphinx is probably low on my list of priorities, but I was just curious if there was a specific reason for keeping the docs at the older version.
>
>
> There's no specific reason for this.  We setup Sphinx a while ago and only upgraded once to get markdown support (which is now the preferred format for new docs).  The only constraint on upgrading to 2.x would be is it available on our minimum supported platform, or are we willing to have a higher minimum for generating the docs.
There recently was a disscussion about this in phabricator (i think? i
can't seem to find it right now).
That version is way too new, it's not even in debian sid; enforcing it
would be limiting.

Thanks Michael and Roman. That makes sense.
 

>>
>> Back in 2012, there was a commit that removed the sidebar from the Docs page. Does anyone know/remember why this was done? I checked the commit message but it’s fairly short and doesn’t provide much context.
>
>
> Who committed it?

Sean Silva's listed as the commit author.

----

I had another question that I was going to start a new thread for, but I'll just add here instead...

ReleaseNotes.rst file - http://llvm.org/docs/ReleaseNotes.html


I was reviewing the commit history for this file in Github, and it appears that it's been worked on for quite a while (as in years). Can someone provide some context as to its purpose?


My guess, based on the commit history, is that it’s a “living” document that folks contribute to for each upcoming release. Meaning it’s constantly being updated. Is my understanding correct? 


 
>
> - Michael Spencer
Roman

> _______________________________________________
> LLVM Developers mailing list
> [hidden email]
> https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev

_______________________________________________
LLVM Developers mailing list
[hidden email]
https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev
Reply | Threaded
Open this post in threaded view
|

Re: [llvm-dev] Introduction and Question about Docs

Rajesh S R via llvm-dev
via llvm-dev <[hidden email]> writes:

> On Tue, Aug 20, 2019 at 12:36 PM Roman Lebedev <[hidden email]> wrote:
>
>> On Tue, Aug 20, 2019 at 9:25 PM Michael Spencer via llvm-dev
>> <[hidden email]> wrote:
>> >
>> > On Mon, Aug 19, 2019 at 12:38 PM via llvm-dev <[hidden email]>
>> wrote:
>> >>
>> >> Hi everyone. My name is DeForest Richards. I’m the technical writer who
>> was selected to work on the LLVM project as part of the Google Season of
>> Docs program. I’ll be helping to restructure the documentation page(s) to
>> make it easier for new and existing users to navigate the LLVM docs.
>> >>
>> >>
>> >> I’m currently reviewing the existing docs, so you’ll probably see me
>> posting questions over the next several weeks. That said, I do have a
>> couple of quick questions that I wanted to ask right now…
>> >>
>> >>
>> >> I noticed that the LLVM Docs currently use Sphinx 1.7.6, which is an
>> older version. (I believe 2.x is the latest version.) Is this intentional?
>> Updating to the latest version of Sphinx is probably low on my list of
>> priorities, but I was just curious if there was a specific reason for
>> keeping the docs at the older version.
>> >
>> >
>> > There's no specific reason for this.  We setup Sphinx a while ago and
>> only upgraded once to get markdown support (which is now the preferred
>> format for new docs).  The only constraint on upgrading to 2.x would be is
>> it available on our minimum supported platform, or are we willing to have a
>> higher minimum for generating the docs.
>> There recently was a disscussion about this in phabricator (i think? i
>> can't seem to find it right now).
>> That version is way too new, it's not even in debian sid; enforcing it
>> would be limiting.
>>
>
> Thanks Michael and Roman. That makes sense.
>
>
>>
>> >>
>> >> Back in 2012, there was a commit that removed the sidebar from the Docs
>> page. Does anyone know/remember why this was done? I checked the commit
>> message but it’s fairly short and doesn’t provide much context.
>> >
>> >
>> > Who committed it?
>>
>
> Sean Silva's listed as the commit author.
>
> ----
>
> I had another question that I was going to start a new thread for, but I'll
> just add here instead...
>
> ReleaseNotes.rst file - http://llvm.org/docs/ReleaseNotes.html
>
>
> I was reviewing the commit history for this file in Github, and it appears
> that it's been worked on for quite a while (as in years). Can someone
> provide some context as to its purpose?
>
> My guess, based on the commit history, is that it’s a “living” document
> that folks contribute to for each upcoming release. Meaning it’s constantly
> being updated. Is my understanding correct?

Yes, people add to this when they add changes that should be called out
during the next release. Each time we cut a branch for a release we
"reset" the version of this document on trunk to an empty one.

>> >
>> > - Michael Spencer
>> Roman
>>
>> > _______________________________________________
>> > LLVM Developers mailing list
>> > [hidden email]
>> > https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev
>>
> _______________________________________________
> LLVM Developers mailing list
> [hidden email]
> https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev
_______________________________________________
LLVM Developers mailing list
[hidden email]
https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev
Reply | Threaded
Open this post in threaded view
|

Re: [llvm-dev] Introduction and Question about Docs

Rajesh S R via llvm-dev
Got it. Thanks!

On Tue, Aug 20, 2019, 1:59 PM Justin Bogner <[hidden email]> wrote:
via llvm-dev <[hidden email]> writes:
> On Tue, Aug 20, 2019 at 12:36 PM Roman Lebedev <[hidden email]> wrote:
>
>> On Tue, Aug 20, 2019 at 9:25 PM Michael Spencer via llvm-dev
>> <[hidden email]> wrote:
>> >
>> > On Mon, Aug 19, 2019 at 12:38 PM via llvm-dev <[hidden email]>
>> wrote:
>> >>
>> >> Hi everyone. My name is DeForest Richards. I’m the technical writer who
>> was selected to work on the LLVM project as part of the Google Season of
>> Docs program. I’ll be helping to restructure the documentation page(s) to
>> make it easier for new and existing users to navigate the LLVM docs.
>> >>
>> >>
>> >> I’m currently reviewing the existing docs, so you’ll probably see me
>> posting questions over the next several weeks. That said, I do have a
>> couple of quick questions that I wanted to ask right now…
>> >>
>> >>
>> >> I noticed that the LLVM Docs currently use Sphinx 1.7.6, which is an
>> older version. (I believe 2.x is the latest version.) Is this intentional?
>> Updating to the latest version of Sphinx is probably low on my list of
>> priorities, but I was just curious if there was a specific reason for
>> keeping the docs at the older version.
>> >
>> >
>> > There's no specific reason for this.  We setup Sphinx a while ago and
>> only upgraded once to get markdown support (which is now the preferred
>> format for new docs).  The only constraint on upgrading to 2.x would be is
>> it available on our minimum supported platform, or are we willing to have a
>> higher minimum for generating the docs.
>> There recently was a disscussion about this in phabricator (i think? i
>> can't seem to find it right now).
>> That version is way too new, it's not even in debian sid; enforcing it
>> would be limiting.
>>
>
> Thanks Michael and Roman. That makes sense.
>
>
>>
>> >>
>> >> Back in 2012, there was a commit that removed the sidebar from the Docs
>> page. Does anyone know/remember why this was done? I checked the commit
>> message but it’s fairly short and doesn’t provide much context.
>> >
>> >
>> > Who committed it?
>>
>
> Sean Silva's listed as the commit author.
>
> ----
>
> I had another question that I was going to start a new thread for, but I'll
> just add here instead...
>
> ReleaseNotes.rst file - http://llvm.org/docs/ReleaseNotes.html
>
>
> I was reviewing the commit history for this file in Github, and it appears
> that it's been worked on for quite a while (as in years). Can someone
> provide some context as to its purpose?
>
> My guess, based on the commit history, is that it’s a “living” document
> that folks contribute to for each upcoming release. Meaning it’s constantly
> being updated. Is my understanding correct?

Yes, people add to this when they add changes that should be called out
during the next release. Each time we cut a branch for a release we
"reset" the version of this document on trunk to an empty one.

>> >
>> > - Michael Spencer
>> Roman
>>
>> > _______________________________________________
>> > LLVM Developers mailing list
>> > [hidden email]
>> > https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev
>>
> _______________________________________________
> LLVM Developers mailing list
> [hidden email]
> https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev

_______________________________________________
LLVM Developers mailing list
[hidden email]
https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev
Reply | Threaded
Open this post in threaded view
|

Re: [llvm-dev] Introduction and Question about Docs

Rajesh S R via llvm-dev
In reply to this post by Rajesh S R via llvm-dev
I don't think our current situation for Markdown versus RST is good unfortunately. There are issues with the inter-file links between RST and Markdown documents, so we're actually in the process of changing the new markdown docs for some of the LLVM binary tools to RST in the CommandGuide directory at least. Some related reviews:

https://reviews.llvm.org/D66305 - switching to RST from MD for new docs
https://reviews.llvm.org/D63292 - attempted workaround for old recommonmark versions
https://reviews.llvm.org/D63211 - local docs build fix attempt (this thread contains a lot of background on what the problem is)

And mailing list threads:

https://lists.llvm.org/pipermail/llvm-dev/2018-March/122234.html - Original proposal to add Markdown support
http://lists.llvm.org/pipermail/llvm-dev/2019-June/133038.html - My analysis of the problems with different recommonmark and Sphinx versions, which might indicate problems with updating. Follow-up comments point out that only recommonmark 0.4.0 is available on Ubuntu repos, so people didn't want to update the build bots via pip to get a working version.

To be clear, I have no issues with us using Markdown, or updating our Sphinx etc versions, if they work.

James


On Tue, 20 Aug 2019 at 19:37, Roman Lebedev via llvm-dev <[hidden email]> wrote:
On Tue, Aug 20, 2019 at 9:25 PM Michael Spencer via llvm-dev
<[hidden email]> wrote:
>
> On Mon, Aug 19, 2019 at 12:38 PM via llvm-dev <[hidden email]> wrote:
>>
>> Hi everyone. My name is DeForest Richards. I’m the technical writer who was selected to work on the LLVM project as part of the Google Season of Docs program. I’ll be helping to restructure the documentation page(s) to make it easier for new and existing users to navigate the LLVM docs.
>>
>>
>> I’m currently reviewing the existing docs, so you’ll probably see me posting questions over the next several weeks. That said, I do have a couple of quick questions that I wanted to ask right now…
>>
>>
>> I noticed that the LLVM Docs currently use Sphinx 1.7.6, which is an older version. (I believe 2.x is the latest version.) Is this intentional? Updating to the latest version of Sphinx is probably low on my list of priorities, but I was just curious if there was a specific reason for keeping the docs at the older version.
>
>
> There's no specific reason for this.  We setup Sphinx a while ago and only upgraded once to get markdown support (which is now the preferred format for new docs).  The only constraint on upgrading to 2.x would be is it available on our minimum supported platform, or are we willing to have a higher minimum for generating the docs.
There recently was a disscussion about this in phabricator (i think? i
can't seem to find it right now).
That version is way too new, it's not even in debian sid; enforcing it
would be limiting.

>>
>> Back in 2012, there was a commit that removed the sidebar from the Docs page. Does anyone know/remember why this was done? I checked the commit message but it’s fairly short and doesn’t provide much context.
>
>
> Who committed it?
>
> - Michael Spencer
Roman

> _______________________________________________
> LLVM Developers mailing list
> [hidden email]
> https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev
_______________________________________________
LLVM Developers mailing list
[hidden email]
https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev

_______________________________________________
LLVM Developers mailing list
[hidden email]
https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev
Reply | Threaded
Open this post in threaded view
|

Re: [llvm-dev] Introduction and Question about Docs

Rajesh S R via llvm-dev
Appreciate the insight. As part of my project, I'd like to figure out a way to implement a tagging scheme for the docs as I'm sure many topics will fall under multiple categories. The goal would be to provide a way for users to filter topics by category, topic/feature, etc.

Based on what you and others have said, I'll need to take into consideration that some docs are written in markdown, others in rst.

On Wed, Aug 21, 2019 at 5:55 AM James Henderson <[hidden email]> wrote:
I don't think our current situation for Markdown versus RST is good unfortunately. There are issues with the inter-file links between RST and Markdown documents, so we're actually in the process of changing the new markdown docs for some of the LLVM binary tools to RST in the CommandGuide directory at least. Some related reviews:

https://reviews.llvm.org/D66305 - switching to RST from MD for new docs
https://reviews.llvm.org/D63292 - attempted workaround for old recommonmark versions
https://reviews.llvm.org/D63211 - local docs build fix attempt (this thread contains a lot of background on what the problem is)

And mailing list threads:

https://lists.llvm.org/pipermail/llvm-dev/2018-March/122234.html - Original proposal to add Markdown support
http://lists.llvm.org/pipermail/llvm-dev/2019-June/133038.html - My analysis of the problems with different recommonmark and Sphinx versions, which might indicate problems with updating. Follow-up comments point out that only recommonmark 0.4.0 is available on Ubuntu repos, so people didn't want to update the build bots via pip to get a working version.

To be clear, I have no issues with us using Markdown, or updating our Sphinx etc versions, if they work.

James


On Tue, 20 Aug 2019 at 19:37, Roman Lebedev via llvm-dev <[hidden email]> wrote:
On Tue, Aug 20, 2019 at 9:25 PM Michael Spencer via llvm-dev
<[hidden email]> wrote:
>
> On Mon, Aug 19, 2019 at 12:38 PM via llvm-dev <[hidden email]> wrote:
>>
>> Hi everyone. My name is DeForest Richards. I’m the technical writer who was selected to work on the LLVM project as part of the Google Season of Docs program. I’ll be helping to restructure the documentation page(s) to make it easier for new and existing users to navigate the LLVM docs.
>>
>>
>> I’m currently reviewing the existing docs, so you’ll probably see me posting questions over the next several weeks. That said, I do have a couple of quick questions that I wanted to ask right now…
>>
>>
>> I noticed that the LLVM Docs currently use Sphinx 1.7.6, which is an older version. (I believe 2.x is the latest version.) Is this intentional? Updating to the latest version of Sphinx is probably low on my list of priorities, but I was just curious if there was a specific reason for keeping the docs at the older version.
>
>
> There's no specific reason for this.  We setup Sphinx a while ago and only upgraded once to get markdown support (which is now the preferred format for new docs).  The only constraint on upgrading to 2.x would be is it available on our minimum supported platform, or are we willing to have a higher minimum for generating the docs.
There recently was a disscussion about this in phabricator (i think? i
can't seem to find it right now).
That version is way too new, it's not even in debian sid; enforcing it
would be limiting.

>>
>> Back in 2012, there was a commit that removed the sidebar from the Docs page. Does anyone know/remember why this was done? I checked the commit message but it’s fairly short and doesn’t provide much context.
>
>
> Who committed it?
>
> - Michael Spencer
Roman

> _______________________________________________
> LLVM Developers mailing list
> [hidden email]
> https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev
_______________________________________________
LLVM Developers mailing list
[hidden email]
https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev

_______________________________________________
LLVM Developers mailing list
[hidden email]
https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev
Reply | Threaded
Open this post in threaded view
|

Re: [llvm-dev] Introduction and Question about Docs

Rajesh S R via llvm-dev
In reply to this post by Rajesh S R via llvm-dev


On Tue, Aug 20, 2019 at 11:54 AM via llvm-dev <[hidden email]> wrote:


On Tue, Aug 20, 2019 at 12:36 PM Roman Lebedev <[hidden email]> wrote:
On Tue, Aug 20, 2019 at 9:25 PM Michael Spencer via llvm-dev
<[hidden email]> wrote:
>
> On Mon, Aug 19, 2019 at 12:38 PM via llvm-dev <[hidden email]> wrote:
>>
>> Hi everyone. My name is DeForest Richards. I’m the technical writer who was selected to work on the LLVM project as part of the Google Season of Docs program. I’ll be helping to restructure the documentation page(s) to make it easier for new and existing users to navigate the LLVM docs.
>>
>>
>> I’m currently reviewing the existing docs, so you’ll probably see me posting questions over the next several weeks. That said, I do have a couple of quick questions that I wanted to ask right now…
>>
>>
>> I noticed that the LLVM Docs currently use Sphinx 1.7.6, which is an older version. (I believe 2.x is the latest version.) Is this intentional? Updating to the latest version of Sphinx is probably low on my list of priorities, but I was just curious if there was a specific reason for keeping the docs at the older version.
>
>
> There's no specific reason for this.  We setup Sphinx a while ago and only upgraded once to get markdown support (which is now the preferred format for new docs).  The only constraint on upgrading to 2.x would be is it available on our minimum supported platform, or are we willing to have a higher minimum for generating the docs.
There recently was a disscussion about this in phabricator (i think? i
can't seem to find it right now).
That version is way too new, it's not even in debian sid; enforcing it
would be limiting.

Thanks Michael and Roman. That makes sense.
 

>>
>> Back in 2012, there was a commit that removed the sidebar from the Docs page. Does anyone know/remember why this was done? I checked the commit message but it’s fairly short and doesn’t provide much context.
>
>
> Who committed it?

Sean Silva's listed as the commit author.


I went back through my mail and found that in r170790 we observed that the sidebar resulted in a redundant table of contents (once from the main table of contents, one in the sidebar). So we removed the sidebar in r170803.

I couldn't find online email archives going back that far, so I've attached a PDF printout of the thread.

This issue may have been exacerbated by our stylesheet/theme making things look ugly.

-- Sean Silva
 

----

I had another question that I was going to start a new thread for, but I'll just add here instead...

ReleaseNotes.rst file - http://llvm.org/docs/ReleaseNotes.html


I was reviewing the commit history for this file in Github, and it appears that it's been worked on for quite a while (as in years). Can someone provide some context as to its purpose?


My guess, based on the commit history, is that it’s a “living” document that folks contribute to for each upcoming release. Meaning it’s constantly being updated. Is my understanding correct? 


 
>
> - Michael Spencer
Roman

> _______________________________________________
> LLVM Developers mailing list
> [hidden email]
> https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev
_______________________________________________
LLVM Developers mailing list
[hidden email]
https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev

_______________________________________________
LLVM Developers mailing list
[hidden email]
https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev

Gmail - [llvm-commits] [llvm] r170790 - _llvm_trunk_docs_Vectorizers.rst.pdf (101K) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: [llvm-dev] Introduction and Question about Docs

Rajesh S R via llvm-dev
Thanks Sean!

I'm thinking about suggesting that it be re-enabled, which is why I asked. But I need to do some more research as to how to configure it. As mentioned in the attached email thread, most topics already have a TOC listed at the top. I'd like the sidebar to instead have a static list of links (for example, links to the Community page, Getting Started, etc.), as well as a search bar. The goal would be to improve overall navigation of the site.

On Sat, Aug 24, 2019 at 7:13 PM Sean Silva <[hidden email]> wrote:


On Tue, Aug 20, 2019 at 11:54 AM via llvm-dev <[hidden email]> wrote:


On Tue, Aug 20, 2019 at 12:36 PM Roman Lebedev <[hidden email]> wrote:
On Tue, Aug 20, 2019 at 9:25 PM Michael Spencer via llvm-dev
<[hidden email]> wrote:
>
> On Mon, Aug 19, 2019 at 12:38 PM via llvm-dev <[hidden email]> wrote:
>>
>> Hi everyone. My name is DeForest Richards. I’m the technical writer who was selected to work on the LLVM project as part of the Google Season of Docs program. I’ll be helping to restructure the documentation page(s) to make it easier for new and existing users to navigate the LLVM docs.
>>
>>
>> I’m currently reviewing the existing docs, so you’ll probably see me posting questions over the next several weeks. That said, I do have a couple of quick questions that I wanted to ask right now…
>>
>>
>> I noticed that the LLVM Docs currently use Sphinx 1.7.6, which is an older version. (I believe 2.x is the latest version.) Is this intentional? Updating to the latest version of Sphinx is probably low on my list of priorities, but I was just curious if there was a specific reason for keeping the docs at the older version.
>
>
> There's no specific reason for this.  We setup Sphinx a while ago and only upgraded once to get markdown support (which is now the preferred format for new docs).  The only constraint on upgrading to 2.x would be is it available on our minimum supported platform, or are we willing to have a higher minimum for generating the docs.
There recently was a disscussion about this in phabricator (i think? i
can't seem to find it right now).
That version is way too new, it's not even in debian sid; enforcing it
would be limiting.

Thanks Michael and Roman. That makes sense.
 

>>
>> Back in 2012, there was a commit that removed the sidebar from the Docs page. Does anyone know/remember why this was done? I checked the commit message but it’s fairly short and doesn’t provide much context.
>
>
> Who committed it?

Sean Silva's listed as the commit author.


I went back through my mail and found that in r170790 we observed that the sidebar resulted in a redundant table of contents (once from the main table of contents, one in the sidebar). So we removed the sidebar in r170803.

I couldn't find online email archives going back that far, so I've attached a PDF printout of the thread.

This issue may have been exacerbated by our stylesheet/theme making things look ugly.

-- Sean Silva
 

----

I had another question that I was going to start a new thread for, but I'll just add here instead...

ReleaseNotes.rst file - http://llvm.org/docs/ReleaseNotes.html


I was reviewing the commit history for this file in Github, and it appears that it's been worked on for quite a while (as in years). Can someone provide some context as to its purpose?


My guess, based on the commit history, is that it’s a “living” document that folks contribute to for each upcoming release. Meaning it’s constantly being updated. Is my understanding correct? 


 
>
> - Michael Spencer
Roman

> _______________________________________________
> LLVM Developers mailing list
> [hidden email]
> https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev
_______________________________________________
LLVM Developers mailing list
[hidden email]
https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev

_______________________________________________
LLVM Developers mailing list
[hidden email]
https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev