[llvm-dev] Introduction and Question about Docs

[James Henderson via llvm-dev]

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/20190821/370301ce/attachment.html>