[llvm-dev] Introduction and Question about Docs

[Sean Silva via llvm-dev]

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/20190824/9ca86152/attachment-0001.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: Gmail - [llvm-commits] [llvm] r170790 - _llvm_trunk_docs_Vectorizers.rst.pdf
Type: application/pdf
Size: 76124 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/llvm-dev/attachments/20190824/9ca86152/attachment-0001.pdf>