[llvm-dev] Introduction and Question about Docs

[Justin Bogner via llvm-dev]

via llvm-dev <llvm-dev at lists.llvm.org> writes:
> 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 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
>> > 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