diff --git a/docs/README.md b/docs/README.md index d53b8675b9..02572ee11e 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,38 +1,93 @@ Docker Documentation ==================== -Documentation -------------- -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) +Overview +-------- -Each of the .rst files under sources reflects a page on the documentation. +The source for Docker documentation is here under ``sources/`` in the +form of .rst files. These files use +[reStructuredText](http://docutils.sourceforge.net/rst.html) +formatting with [Sphinx](http://sphinx-doc.org/) extensions for +structure, cross-linking and indexing. -Installation ------------- +The HTML files are built and hosted on +[readthedocs.org](https://readthedocs.org/projects/docker/), appearing +via proxy on https://docs.docker.io. The HTML files update +automatically after each change to the master or release branch of the +[docker files on GitHub](https://github.com/dotcloud/docker) thanks to +post-commit hooks. The "release" branch maps to the "latest" +documentation and the "master" branch maps to the "master" +documentation. + +**Warning**: The "master" documentation may include features not yet +part of any official docker release. "Master" docs should be used only +for understanding bleeding-edge development and "latest" should be +used for the latest official release. + +If you need to manually trigger a build of an existing branch, then +you can do that through the [readthedocs +interface](https://readthedocs.org/builds/docker/). If you would like +to add new build targets, including new branches or tags, then you +must contact one of the existing maintainers and get your +readthedocs.org account added to the maintainers list, or just file an +issue on GitHub describing the branch/tag and why it needs to be added +to the docs, and one of the maintainers will add it for you. + +Getting Started +--------------- + +To edit and test the docs, you'll need to install the Sphinx tool and +its dependencies. There are two main ways to install this tool: + +Native Installation +................... -* Work in your own fork of the code, we accept pull requests. * Install sphinx: `pip install sphinx` - * Mac OS X: `[sudo] pip-2.7 install sphinx`) + * Mac OS X: `[sudo] pip-2.7 install sphinx` * Install sphinx httpdomain contrib package: `pip install sphinxcontrib-httpdomain` * Mac OS X: `[sudo] pip-2.7 install sphinxcontrib-httpdomain` * If pip is not available you can probably install it using your favorite package manager as **python-pip** +Alternative Installation: Docker Container +.......................................... + +If you're running ``docker`` on your development machine then you may +find it easier and cleaner to use the Dockerfile. This installs Sphinx +in a container, adds the local ``docs/`` directory and builds the HTML +docs inside the container, even starting a simple HTTP server on port +8000 so that you can connect and see your changes. Just run ``docker +build .`` and run the resulting image. This is the equivalent to +``make clean server`` since each container starts clean. + Usage ----- -* Change the `.rst` files with your favorite editor to your liking. -* Run `make docs` to clean up old files and generate new ones. -* Your static website can now be found in the `_build` directory. -* To preview what you have generated run `make server` and open http://localhost:8000/ in your favorite browser. +* Follow the contribution guidelines (``../CONTRIBUTING.md``) +* Work in your own fork of the code, we accept pull requests. +* Change the ``.rst`` files with your favorite editor -- try to keep the + lines short and respect RST and Sphinx conventions. +* Run ``make clean docs`` to clean up old files and generate new ones, + or just ``make docs`` to update after small changes. +* Your static website can now be found in the ``_build`` directory. +* To preview what you have generated run ``make server`` and open + http://localhost:8000/ in your favorite browser. + +``make clean docs`` must complete without any warnings or errors. Working using GitHub's file editor ---------------------------------- -Alternatively, for small changes and typo's you might want to use GitHub's built in file editor. It allows -you to preview your changes right online. Just be careful not to create many commits. + +Alternatively, for small changes and typos you might want to use +GitHub's built in file editor. It allows you to preview your changes +right online (though there can be some differences between GitHub +markdown and Sphinx RST). Just be careful not to create many commits. Images ------ -When you need to add images, try to make them as small as possible (e.g. as gif). + +When you need to add images, try to make them as small as possible +(e.g. as gif). Usually images should go in the same directory as the +.rst file which references them, or in a subdirectory if one already +exists. Notes ----- @@ -41,7 +96,7 @@ lessc ``lessc main.less`` or watched using watch-lessc ``watch-lessc -i main.les Guides on using sphinx ---------------------- -* To make links to certain pages create a link target like so: +* To make links to certain sections create a link target like so: ``` .. _hello_world: @@ -52,7 +107,10 @@ Guides on using sphinx This is.. (etc.) ``` - The ``_hello_world:`` will make it possible to link to this position (page and marker) from all other pages. + The ``_hello_world:`` will make it possible to link to this position + (page and section heading) from all other pages. See the [Sphinx + docs](http://sphinx-doc.org/markup/inline.html#role-ref) for more + information and examples. * Notes, warnings and alarms @@ -68,13 +126,17 @@ Guides on using sphinx * Code examples - Start without $, so it's easy to copy and paste. + * Start without $, so it's easy to copy and paste. + * Use "sudo" with docker to ensure that your command is runnable + even if they haven't [used the *docker* + group](http://docs.docker.io/en/latest/use/basics/#why-sudo). 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/ +* To make the manpages, 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 +