llvm dev - Aug 2019 - Introduction and Question about Docs

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.
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://lists.llvm.org/pipermail/llvm-dev/attachments/20190819/20875efa/attachment.html>

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 <llvm-dev at lists.llvm.org>
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
> llvm-dev at lists.llvm.org
> https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://lists.llvm.org/pipermail/llvm-dev/attachments/20190819/4aca7906/attachment.html>

Thanks! I'm looking forward to helping out with the docs.

On Mon, Aug 19, 2019, 2:22 PM Reid Kleckner <rnk at google.com> 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 <llvm-dev at
lists.llvm.org>
> 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
>> llvm-dev at lists.llvm.org
>> https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev
>>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://lists.llvm.org/pipermail/llvm-dev/attachments/20190819/1d6e928d/attachment.html>

On Mon, Aug 19, 2019 at 12:38 PM via llvm-dev <llvm-dev at lists.llvm.org>
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
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://lists.llvm.org/pipermail/llvm-dev/attachments/20190820/b0ed8373/attachment.html>

On Tue, Aug 20, 2019 at 9:25 PM Michael Spencer via llvm-dev
<llvm-dev at lists.llvm.org> wrote:
>
> On Mon, Aug 19, 2019 at 12:38 PM via llvm-dev <llvm-dev at
lists.llvm.org> 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
> llvm-dev at lists.llvm.org
> https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev