[llvm-dev] Introduction and Question about Docs

[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 <
jh7370.2008 at my.bristol.ac.uk> 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 <
> llvm-dev at lists.llvm.org> 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.
>>
>> >>
>> >> 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
>> _______________________________________________
>> 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/20190823/63ca10f5/attachment.html>