[LLVMbugs] [Bug 12589] New: Move to Sphinx based documentation

[bugzilla-daemon at llvm.org]

http://llvm.org/bugs/show_bug.cgi?id=12589

             Bug #: 12589
           Summary: Move to Sphinx based documentation
           Product: Documentation
           Version: trunk
          Platform: All
        OS/Version: All
            Status: NEW
          Severity: normal
          Priority: P
         Component: General docs
        AssignedTo: unassignedbugs at nondot.org
        ReportedBy: daniel at zuster.org
                CC: llvmbugs at cs.uiuc.edu
    Classification: Unclassified


We should move to using Sphinx based documentation, as part of a general effort
to improve the LLVM documentation.

This is a multi-part effort:

#. Set up basic project structure for using Sphinx for documentation.

   This involves setting up the Sphinx configuration, figuring out how it
should integrate with Makefiles or CMake (e.g., how to integrate with man page
generation while we still have POD based man pages), and implementing
auto-update support on the llvm.org server.

#. Converting existing documentation into reStructured Text / Sphinx.

#. Improving structure of existing documentation.

   This is not directly related to converting to Sphinx, but the existing
documentation organization is really horrible. We basically just have an ad hoc
collection of pages, and the existing groupings are frequently confusing or
wrong.

   As part of the conversion, it would be nice to *at least* make sure that the
top-level overview page provides a reasonable organization for the documents we
have.

#. Update documentation to better integrate with Sphinx.

   There are some specific documents which we should rewrite or update, in
particular the Lexicon page should just become the Sphinx glossary.

   We should also try and make reasonable use of the Sphinx index.

#. Investigate PDF rendering.

   We should try and implement the Sphinx conversion in such a way that we can
generate a reasonably readable PDF for the LLVM documentation. This would be
something nice to archive with releases.

#. Implement better behavior for managing multiple documentation versions.

   We currently archive the documentation with each release, and put at warning
at the top of the TOT documentation (http://llvm.org/docs) that it is the
development documentation.

   It would be nicer to have something like Python does:

     http://docs.python.org/

   where the main documentation page shows the documentation for the most
recent release, and there are handy links on the sidebar to access the
documentation for other releases.

   We will need to resolve this before the 3.2 release, because the Sphinx
documentation will need to be archived slightly differently than we do for
current releases.

-- 
Configure bugmail: http://llvm.org/bugs/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
You are on the CC list for the bug.