[llvm-commits] Refactor Sphinx homepage

Sean Silva silvas at purdue.edu
Thu Jun 21 20:52:16 PDT 2012


> We currently conflate two different topics under the moniker of
> "LLVM": the "LLVM project" (organization, developer policy, website,

Agreed. This is a sticky rhetorical problem. I agree that structural
division of the documentation is the best way to address this. The
titles need to be as unambiguous as possible for this scheme to be
maximally effective, so maybe "LLVM Umbrella Project" should be
preferred to "LLVM Project" in the outline you gave.


> 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?

I like it. It's definitely a huge step up from the current state of affairs.

One thing that I think we need to especially plan on is tutorials.
Tutorials are currently LLVM's biggest weak-spot documentationwise
(other than the horrible organization). Tutorials for LLVM are
woefully lacking, and the few existing ones are hard to find and
bit-rot very quickly. Some of the stuff in the examples/ directory are
awesome, only needing a little bit of human narrative to become
excellent tutorials. The most lacking one is a walkthrough of
examples/Fibonacci IMO.

As far as moving to this new documentation organization, I think that
a good plan is to make a push to get everything into Sphinx. Once that
is done, this organization can be imposed through the toctree with
minimal churn. Once that is done, we will be able to see the outline
of the documentation on one page, and it should be easy to identify
and fill in any missing pieces.


There's a really good talk about documentation by one of the lead
Django developers at
<http://blip.tv/pycon-us-videos-2009-2010-2011/pycon-2011-writing-great-documentation-4899042>.
Slides at <http://bit.ly/i8o8B4> (look at slide 24 and the immediately
preceding slides). Another presentation that is good has slides at
<http://www.oscon.com/oscon2010/public/schedule/detail/14000>.

Both emphasize 4 main divisions of documentation and that these
divisions are fractal in that they apply to different levels (whole
project, single subsystem, single module, etc). Definitely worth
checking out.

--Sean Silva

On Thu, Jun 21, 2012 at 2:01 PM, Daniel Dunbar <daniel at zuster.org> wrote:
>
> 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