diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a7d73273ae..43137c67e2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -59,8 +59,10 @@ Submit unit tests for your changes. Go has a great test framework built in; use it! Take a look at existing tests for inspiration. Run the full test suite on your branch before submitting a pull request. -Make sure you include relevant updates or additions to documentation when -creating or modifying features. +Update the documentation when creating or modifying features. Test +your documentation changes for clarity, concision, and correctness, as +well as a clean docmuent build. See ``docs/README.md`` for more +information on building the docs and how docs get released. Write clean code. Universally formatted code promotes ease of writing, reading, and maintenance. Always run `go fmt` before committing your changes. Most 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 + diff --git a/hack/RELEASE-CHECKLIST.md b/hack/RELEASE-CHECKLIST.md index 0adbdba6dd..5f873c6c5c 100644 --- a/hack/RELEASE-CHECKLIST.md +++ b/hack/RELEASE-CHECKLIST.md @@ -57,7 +57,13 @@ EXAMPLES: FIXME -### 5. Commit and create a pull request to the "release" branch +### 5. Test the docs + +Make sure that your tree includes documentation for any modified or +new features, syntax or semantic changes. Instructions for building +the docs are in ``docs/README.md`` + +### 6. Commit and create a pull request to the "release" branch ```bash git add CHANGELOG.md @@ -65,9 +71,9 @@ git commit -m "Bump version to $VERSION" git push origin bump_$VERSION ``` -### 6. Get 2 other maintainers to validate the pull request +### 7. Get 2 other maintainers to validate the pull request -### 7. Merge the pull request and apply tags +### 8. Merge the pull request and apply tags ```bash git checkout release @@ -78,7 +84,13 @@ git push git push --tags ``` -### 8. Publish binaries +Merging the pull request to the release branch will automatically +update the documentation on the "latest" revision of the docs. You +should see the updated docs 5-10 minutes after the merge. The docs +will appear on http://docs.docker.io/. For more information about +documentation releases, see ``docs/README.md`` + +### 9. Publish binaries To run this you will need access to the release credentials. Get them from [the infrastructure maintainers]( @@ -100,6 +112,6 @@ use get-nightly.docker.io for general testing, and once everything is fine, switch to get.docker.io). -### 9. Rejoice! +### 10. Rejoice! Congratulations! You're done.