[llvm-dev] Introduction and Question about Docs

[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 <chisophugis at gmail.com> wrote:

>
>
> On Tue, Aug 20, 2019 at 11:54 AM via llvm-dev <llvm-dev at lists.llvm.org>
> wrote:
>
>>
>>
>> On Tue, Aug 20, 2019 at 12:36 PM Roman Lebedev <lebedev.ri at gmail.com>
>> wrote:
>>
>>> 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.
>>>
>>
>> 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
>>> > llvm-dev at lists.llvm.org
>>> > https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev
>>>
>> _______________________________________________
>> 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/20190826/3b7ae071/attachment.html>