[llvm-commits] Refactor Sphinx homepage

Daniel Dunbar daniel at zuster.org
Thu Jun 21 14:01:38 PDT 2012


Hi Sean,

I'm a bit behind the times, so hopefully this reply isn't too out of
date, but I'm super happy to see you are interested in working on
this.

I completely agree the current division is terrible, I also very much
wanted to refactor it but decided it was too big of a project to take
on at the same time as the conversion to .rst, so I figured I would
translate the old docs and then think about the right way to
restructure.

One of the big problems with the current structure is that it although
it ostensibly tries to divide the documentation into logical sections
for different audiences ("users" vs "developers"), the division is
done very poorly. We also have a lot of little tiny bits of
information posing as "guides", but these aren't integrated into any
kind of cohesive whole.

At the moment, one of the big problems with the current division is
that it is hard to do better than just read *all* the docs when you
want to find out stuff about LLVM, because it isn't clear where you
should be looking for information.

I generally agree with your plan (I think) of merging the various top
level documents, with one exception.

We currently conflate two different topics under the moniker of
"LLVM": the "LLVM project" (organization, developer policy, website,
mailing lists, etc.), and the "LLVM core" (the LLVM library which is a
part of the LLVM project). Chris and I discussed this problem
recently, and I think it would behoove us to try and keep these two
topics separate  (and keep the documentation for them separate).

The next direction I would propose for the technical content (the bulk
of what is there) is to try and organize the leaf documents into
something resembling more of a "manual". The division of documents
between "design & overview", "user guides", "api clients", and
"subsystems" is really arbitrary and not at all helpful. I believe
this started as an idea to separate documentation to appeal to
different audiences, but the division between the various groups is
too arbitrary.

Instead, I would propose that we organize the documentation more along
the lines of the division and structure that exists in the project,
and clearly communicate the TOC, and then let users find the documents
they need.

With that in mind, here is a rough 10 minute outline of how I would
organize the "LLVM manual", focused at natural divisions of the
project itself (not of its audience):

Introduction
LLVM Project
  Overview
  Development Policy (DeveloperPolicy)
  Coding Standards (CodingStandards)
  Release Process (HowToReleaseLLVM)
  Project Guide (Projects)
  Mailing Lists (mailing_lists)
LLVM Core
  Getting Started (Getting Started)
  Architectural Overview
    (cover the interaction between IR, mid-level stuff, backend stuff,
and other pieces like the JIT)
  Support libraries
    Data structures
    System library
  The Intermediate Representation
    LangRef
    The C++ API to the IR
    llvm-as, llvm-dis, llvm-extract, etc.
    The bit code format
    ... other stuff (like GEP faq) ...
  Mid-Level Optimization
    Overview
    Pass Manager
    Alias Analysis
    The 'opt' tool
    ...
  Backend Infrastructure
     Target independent code generator
     tablegen
     The 'llc' tool
     Writing a new backend
     ...

In my mind, this kind of table of contents follows a structure that is
much more related to the way to code / tasks are organized, which
makes it easier to know where new documentation needs to fit, and how
to slice up the existing documentation to fit it into a more useful
structure.

What do you think of this general idea?

 - Daniel

On Sat, Jun 9, 2012 at 12:49 AM, Sean Silva <silvas at purdue.edu> wrote:
> This is a first step towards structuring the Sphinx docs better to make them
> easier to browse and use. It doesn't change the structure or contents of the
> docs at all.
>
> In a future patch, I'm planning on taking each of
>
>    design_and_overview.rst
>    userguides.rst
>    programming.rst
>    subsystems.rst
>    development_process.rst
>    mailing_lists.rst
>
> and reintegrating them into the homepage. This will be similar to how the
> old html docs homepage was, so it will be familiar (and super-fast to search
> with Ctrl-f, which I've seen at least one other person miss). The current
> setup is just really bulky and hard to navigate, being on different pages,
> when there's really not that much there, certainly not enough to merit
> splitting up.
>
> Another thing, but an important one, is that the way the current docs are
> laid out in the reST source makes the end result incredibly ugly. For
> example, the lists are indented by a space or two in the .rst file, which
> causes Sphinx to emit a list of indented bullets, even though the bullets
> are logically at the top level. Also, semantically, they should be
> definition lists, not bulleted lists.
>
> I'll be fixing all of these things once I get my feet wet with this patch.
>
> Feedback on which direction to take the docs after that would be
> appreciated.
>
> --Sean Silva
>
> _______________________________________________
> llvm-commits mailing list
> llvm-commits at cs.uiuc.edu
> http://lists.cs.uiuc.edu/mailman/listinfo/llvm-commits
>




More information about the llvm-commits mailing list