From f4b63d9eeaddae6cb15775bea13ec4bca6e115da Mon Sep 17 00:00:00 2001 From: Thatcher Peskens Date: Thu, 25 Jul 2013 17:19:58 -0700 Subject: [PATCH 1/3] Enabled the docs to generate manpages. * changed conf.py to reference toctree.rst instead of index * Added note to README to upgrade your sphinx to the latest version to prevent a bug with .. note:: blocks. --- docs/README.md | 5 +++-- docs/sources/conf.py | 6 +++--- docs/sources/use/builder.rst | 4 ++-- 3 files changed, 8 insertions(+), 7 deletions(-) diff --git a/docs/README.md b/docs/README.md index 74ab2bd0cd..32be549ef5 100644 --- a/docs/README.md +++ b/docs/README.md @@ -39,8 +39,6 @@ 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`` @@ -75,3 +73,6 @@ Guides on using sphinx * Code examples Start without $, so it's easy to copy and paste. + +* To make the manpages, simply run 'make man'. Pleae note there is a bug in spinx 1.1.3 which makes this fail. +Upgrade to the latest version of sphinx. \ No newline at end of file diff --git a/docs/sources/conf.py b/docs/sources/conf.py index ea8e1f43f0..b4c23f0c58 100644 --- a/docs/sources/conf.py +++ b/docs/sources/conf.py @@ -203,7 +203,7 @@ latex_elements = { # 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 @@ latex_documents = [ # 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 @@ man_pages = [ # (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'), ] diff --git a/docs/sources/use/builder.rst b/docs/sources/use/builder.rst index aa2fd6b92a..4a9786ee47 100644 --- a/docs/sources/use/builder.rst +++ b/docs/sources/use/builder.rst @@ -107,8 +107,8 @@ the image. This is functionally equivalent to running ``docker commit -run '{"Cmd": }'`` 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 From 26229d78f2b77592ab6761a4ffce38ab7d859f3b Mon Sep 17 00:00:00 2001 From: Thatcher Peskens Date: Wed, 31 Jul 2013 13:44:10 -0700 Subject: [PATCH 2/3] Updated docs README with instructions to preview the generated manfile, and where to get the one generated by sphinx. --- docs/README.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/docs/README.md b/docs/README.md index 32be549ef5..7d7b67ca04 100644 --- a/docs/README.md +++ b/docs/README.md @@ -74,5 +74,12 @@ Guides on using sphinx Start without $, so it's easy to copy and paste. +Manpages +-------- + * To make the manpages, simply run 'make man'. Pleae note there is a bug in spinx 1.1.3 which makes this fail. -Upgrade to the latest version of sphinx. \ No newline at end of file +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/ \ No newline at end of file From ad3b091d535cde5544ec3c11da4cf8d9b278a325 Mon Sep 17 00:00:00 2001 From: Thatcher Date: Wed, 31 Jul 2013 13:59:56 -0700 Subject: [PATCH 3/3] Some more improvements on the docs readme. Removed references to website. --- docs/README.md | 19 +++++++------------ 1 file changed, 7 insertions(+), 12 deletions(-) diff --git a/docs/README.md b/docs/README.md index 7d7b67ca04..1a40b5bb5c 100644 --- a/docs/README.md +++ b/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,13 +34,11 @@ Images ------ When you need to add images, try to make them as small as possible (e.g. as gif). - Notes ----- * 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: @@ -77,9 +73,8 @@ Guides on using sphinx Manpages -------- -* To make the manpages, simply run 'make man'. Pleae note there is a bug in spinx 1.1.3 which makes this fail. +* 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/ \ No newline at end of file +* The manpages are also autogenerated by our hosted readthedocs here: http://docs-docker.dotcloud.com/projects/docker/downloads/