X-Git-Url: http://demsky.eecs.uci.edu/git/?a=blobdiff_plain;f=docs%2FREADME.txt;h=31764b2951b2f9d5b04dba8340bc757e8c8a7391;hb=813f44a29fd0fd140127023222d0633e23783bcc;hp=5ddd599d8a7896ab267e38a9315a6c21d73b37d7;hpb=77ed3424e41cfb06600dbc7c138a565be71cfb95;p=oota-llvm.git

diff --git a/docs/README.txt b/docs/README.txt
index 5ddd599d8a7..31764b2951b 100644
--- a/docs/README.txt
+++ b/docs/README.txt
@@ -1,12 +1,51 @@
 LLVM Documentation
 ==================
 
-The LLVM documentation is currently written in two formats:
+LLVM's documentation is written in reStructuredText, a lightweight
+plaintext markup language (file extension `.rst`). While the
+reStructuredText documentation should be quite readable in source form, it
+is mostly meant to be processed by the Sphinx documentation generation
+system to create HTML pages which are hosted on <http://llvm.org/docs/> and
+updated after every commit. Manpage output is also supported, see below.
 
-  * Plain HTML documentation.
+If you instead would like to generate and view the HTML locally, install
+Sphinx <http://sphinx-doc.org/> and then do:
 
-  * reStructured Text documentation using the Sphinx documentation generator. It
-    is currently tested with Sphinx 1.1.3. 
+    cd docs/
+    make -f Makefile.sphinx
+    $BROWSER _build/html/index.html
 
-    For more information, see the "Sphinx Introduction for LLVM Developers"
-    document.
+The mapping between reStructuredText files and generated documentation is
+`docs/Foo.rst` <-> `_build/html/Foo.html` <-> `http://llvm.org/docs/Foo.html`.
+
+If you are interested in writing new documentation, you will want to read
+`SphinxQuickstartTemplate.rst` which will get you writing documentation
+very fast and includes examples of the most important reStructuredText
+markup syntax.
+
+Manpage Output
+===============
+
+Building the manpages is similar to building the HTML documentation. The
+primary difference is to use the `man` makefile target, instead of the
+default (which is `html`). Sphinx then produces the man pages in the
+directory `_build/man/`.
+
+    cd docs/
+    make -f Makefile.sphinx man
+    man -l _build/man/FileCheck.1
+
+The correspondence between .rst files and man pages is
+`docs/CommandGuide/Foo.rst` <-> `_build/man/Foo.1`.
+These .rst files are also included during HTML generation so they are also
+viewable online (as noted above) at e.g.
+`http://llvm.org/docs/CommandGuide/Foo.html`.
+
+Checking links
+==============
+
+The reachability of external links in the documentation can be checked by
+running:
+
+    cd docs/
+    make -f Makefile.sphinx linkcheck