Merge pull request moby#1303 from dhrp/update-spinx-for-man

Enabled the docs to generate manpages.

Author: dhrp

docs/README.md

@@ -1,14 +1,12 @@
-Docker documentation and website
-================================
+Docker Documentation
+====================
 
 Documentation
 -------------
-This is your definite place to contribute to the docker documentation. The documentation is generated from the
-.rst files under sources.
-
-The folder also contains the other files to create the http://docker.io website, but you can generally ignore
-most of those.
+This is your definite place to contribute to the docker documentation. After each push to master the documentation
+is automatically generated and made available on [docs.docker.io](http://docs.docker.io)
 
+Each of the .rst files under sources reflects a page on the documentation. 
 
 Installation
 ------------
@@ -36,15 +34,11 @@ Images
 ------
 When you need to add images, try to make them as small as possible (e.g. as gif).
 
-
 Notes
 -----
-* The index.html and gettingstarted.html files are copied from the source dir to the output dir without modification.
-So changes to those pages should be made directly in html
 * For the template the css is compiled from less. When changes are needed they can be compiled using
 lessc ``lessc main.less`` or watched using watch-lessc ``watch-lessc -i main.less -o main.css``
 
-
 Guides on using sphinx
 ----------------------
 * To make links to certain pages create a link target like so:
@@ -75,3 +69,12 @@ Guides on using sphinx
 * Code examples
 
   Start without $, so it's easy to copy and paste.
+
+Manpages
+--------
+
+* To make the manpages, simply run 'make man'. Please note there is a bug in spinx 1.1.3 which makes this fail.
+Upgrade to the latest version of sphinx.
+* Then preview the manpage by running `man _build/man/docker.1`, where _build/man/docker.1 is the path to the generated
+manfile
+* The manpages are also autogenerated by our hosted readthedocs here: http://docs-docker.dotcloud.com/projects/docker/downloads/

docs/sources/conf.py

@@ -203,7 +203,7 @@
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title, author, documentclass [howto/manual]).
 latex_documents = [
-  ('index', 'Docker.tex', u'Docker Documentation',
+  ('toctree', 'Docker.tex', u'Docker Documentation',
    u'Team Docker', 'manual'),
 ]
 
@@ -233,7 +233,7 @@
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    ('index', 'docker', u'Docker Documentation',
+    ('toctree', 'docker', u'Docker Documentation',
      [u'Team Docker'], 1)
 ]
 
@@ -247,7 +247,7 @@
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-  ('index', 'Docker', u'Docker Documentation',
+  ('toctree', 'Docker', u'Docker Documentation',
    u'Team Docker', 'Docker', 'One line description of project.',
    'Miscellaneous'),
 ]

docs/sources/use/builder.rst

@@ -107,8 +107,8 @@ the image.  This is functionally equivalent to running ``docker commit
 -run '{"Cmd": <command>}'`` outside the builder.
 
 .. note::
-    Don't confuse `RUN` with `CMD`. `RUN` actually runs a
-    command and commits the result; `CMD` does not execute anything at
+    Don't confuse ``RUN`` with ``CMD``. ``RUN`` actually runs a
+    command and commits the result; ``CMD`` does not execute anything at
     build time, but specifies the intended command for the image.
 
 3.5 EXPOSE