1. docker
  2. Commit cd455ca6fa3a899153880a7b95b9d07762b4c97c
Browse code

Fix #1919 document how to edit and release docs.

Andy Rothfusz authored on 2013/10/16 07:52:21
Showing 3 changed files
CONTRIBUTING.md
History View file @ cd455ca
... ... 
@@ -59,8 +59,10 @@ Submit unit tests for your changes.  Go has a great test framework built in; use
59 59 
 it! Take a look at existing tests for inspiration. Run the full test suite on
60 60 
 your branch before submitting a pull request.
61 61
62 
-Make sure you include relevant updates or additions to documentation when
63 
-creating or modifying features.
62 
+Update the documentation when creating or modifying features. Test
63 
+your documentation changes for clarity, concision, and correctness, as
64 
+well as a clean docmuent build. See ``docs/README.md`` for more
65 
+information on building the docs and how docs get released.
64 66
65 67 
 Write clean code. Universally formatted code promotes ease of writing, reading,
66 68 
 and maintenance. Always run `go fmt` before committing your changes. Most
docs/README.md
History View file @ cd455ca
... ... 
@@ -1,38 +1,93 @@
1 1 
 Docker Documentation
2 2 
 ====================
3 3
4 
-Documentation
5 
-This is your definite place to contribute to the docker documentation. After each push to master the documentation
6 
-is automatically generated and made available on [docs.docker.io](http://docs.docker.io)
7 
-
8 
-Each of the .rst files under sources reflects a page on the documentation.
4 
+Overview
5 
+--------
9 6
10 
-Installation
7 
+The source for Docker documentation is here under ``sources/`` in the
8 
+form of .rst files. These files use
9 
+[reStructuredText](http://docutils.sourceforge.net/rst.html)
10 
+formatting with [Sphinx](http://sphinx-doc.org/) extensions for
11 
+structure, cross-linking and indexing.
12 
+
13 
+The HTML files are built and hosted on
14 
+[readthedocs.org](https://readthedocs.org/projects/docker/), appearing
15 
+via proxy on https://docs.docker.io. The HTML files update
16 
+automatically after each change to the master or release branch of the
17 
+[docker files on GitHub](https://github.com/dotcloud/docker) thanks to
18 
+post-commit hooks. The "release" branch maps to the "latest"
19 
+documentation and the "master" branch maps to the "master"
20 
+documentation.
21 
+
22 
+**Warning**: The "master" documentation may include features not yet
23 
+part of any official docker release. "Master" docs should be used only
24 
+for understanding bleeding-edge development and "latest" should be
25 
+used for the latest official release.
26 
+
27 
+If you need to manually trigger a build of an existing branch, then
28 
+you can do that through the [readthedocs
29 
+interface](https://readthedocs.org/builds/docker/). If you would like
30 
+to add new build targets, including new branches or tags, then you
31 
+must contact one of the existing maintainers and get your
32 
+readthedocs.org account added to the maintainers list, or just file an
33 
+issue on GitHub describing the branch/tag and why it needs to be added
34 
+to the docs, and one of the maintainers will add it for you.
35 
+
36 
+Getting Started
37 
+---------------
38 
+
39 
+To edit and test the docs, you'll need to install the Sphinx tool and
40 
+its dependencies. There are two main ways to install this tool:
41 
+
42 
+Native Installation
43 
+...................
11 44
12 
-* Work in your own fork of the code, we accept pull requests.
13 45 
 * Install sphinx: `pip install sphinx`
14 
-    * Mac OS X: `[sudo] pip-2.7 install sphinx`)
46 
+    * Mac OS X: `[sudo] pip-2.7 install sphinx`
15 47 
 * Install sphinx httpdomain contrib package: `pip install sphinxcontrib-httpdomain`
16 48 
     * Mac OS X: `[sudo] pip-2.7 install sphinxcontrib-httpdomain`
17 49 
 * If pip is not available you can probably install it using your favorite package manager as **python-pip**
18 50
51 
+Alternative Installation: Docker Container
52 
+..........................................
53 
+
54 
+If you're running ``docker`` on your development machine then you may
55 
+find it easier and cleaner to use the Dockerfile. This installs Sphinx
56 
+in a container, adds the local ``docs/`` directory and builds the HTML
57 
+docs inside the container, even starting a simple HTTP server on port
58 
+8000 so that you can connect and see your changes. Just run ``docker
59 
+build .`` and run the resulting image. This is the equivalent to
60 
+``make clean server`` since each container starts clean.
61 
+
19 62 
 Usage
20 63 
 -----
21 
-* Change the `.rst` files with your favorite editor to your liking.
22 
-* Run `make docs` to clean up old files and generate new ones.
23 
-* Your static website can now be found in the `_build` directory.
24 
-* To preview what you have generated run `make server` and open http://localhost:8000/ in your favorite browser.
64 
+* Follow the contribution guidelines (``../CONTRIBUTING.md``)
65 
+* Work in your own fork of the code, we accept pull requests.
66 
+* Change the ``.rst`` files with your favorite editor -- try to keep the
67 
+  lines short and respect RST and Sphinx conventions.
68 
+* Run ``make clean docs`` to clean up old files and generate new ones,
69 
+  or just ``make docs`` to update after small changes.
70 
+* Your static website can now be found in the ``_build`` directory.
71 
+* To preview what you have generated run ``make server`` and open
72 
+  http://localhost:8000/ in your favorite browser.
73 
+
74 
+``make clean docs`` must complete without any warnings or errors.
25 75
26 76 
 Working using GitHub's file editor
27 77 
 ----------------------------------
28 
-Alternatively, for small changes and typo's you might want to use GitHub's built in file editor. It allows
29 
-you to preview your changes right online. Just be careful not to create many commits.
78 
+
79 
+Alternatively, for small changes and typos you might want to use
80 
+GitHub's built in file editor. It allows you to preview your changes
81 
+right online (though there can be some differences between GitHub
82 
+markdown and Sphinx RST). Just be careful not to create many commits.
30 83
31 84 
 Images
32 85 
 ------
33 
-When you need to add images, try to make them as small as possible (e.g. as gif).
86 
+
87 
+When you need to add images, try to make them as small as possible
88 
+(e.g. as gif). Usually images should go in the same directory as the
89 
+.rst file which references them, or in a subdirectory if one already
90 
+exists.
34 91
35 92 
 Notes
36 93 
 -----
... ... 
@@ -41,7 +96,7 @@ lessc ``lessc main.less`` or watched using watch-lessc ``watch-lessc -i main.les
41 41
42 42 
 Guides on using sphinx
43 43 
 ----------------------
44 
-* To make links to certain pages create a link target like so:
44 
+* To make links to certain sections create a link target like so:
45 45
46 46 
   ```
47 47 
     .. _hello_world:
... ... 
@@ -52,7 +107,10 @@ Guides on using sphinx
52 52 
     This is.. (etc.)
53 53 
   ```
54 54
55 
-  The ``_hello_world:`` will make it possible to link to this position (page and marker) from all other pages.
55 
+  The ``_hello_world:`` will make it possible to link to this position
56 
+  (page and section heading) from all other pages. See the [Sphinx
57 
+  docs](http://sphinx-doc.org/markup/inline.html#role-ref) for more
58 
+  information and examples.
56 59
57 60 
 * Notes, warnings and alarms
58 61
... ... 
@@ -68,13 +126,17 @@ Guides on using sphinx
68 68
69 69 
 * Code examples
70 70
71 
-  Start without $, so it's easy to copy and paste.
71 
+  * Start without $, so it's easy to copy and paste.
72 
+  * Use "sudo" with docker to ensure that your command is runnable
73 
+    even if they haven't [used the *docker*
74 
+    group](http://docs.docker.io/en/latest/use/basics/#why-sudo).
72 75
73 76 
 Manpages
74 77 
 --------
75 78
76 
-* To make the manpages, simply run 'make man'. Please note there is a bug in spinx 1.1.3 which makes this fail.
77 
-Upgrade to the latest version of sphinx.
78 
-* Then preview the manpage by running `man _build/man/docker.1`, where _build/man/docker.1 is the path to the generated
79 
-manfile
80 
-* The manpages are also autogenerated by our hosted readthedocs here: http://docs-docker.dotcloud.com/projects/docker/downloads/
79 
+* To make the manpages, run ``make man``. Please note there is a bug
80 
+  in spinx 1.1.3 which makes this fail.  Upgrade to the latest version
81 
+  of Sphinx.
82 
+* Then preview the manpage by running ``man _build/man/docker.1``,
83 
+  where ``_build/man/docker.1`` is the path to the generated manfile
84 
+
hack/RELEASE-CHECKLIST.md
History View file @ cd455ca
... ... 
@@ -57,7 +57,13 @@ EXAMPLES:
57 57
58 58 
 FIXME
59 59
60 
-### 5. Commit and create a pull request to the "release" branch
60 
+### 5. Test the docs
61 
+
62 
+Make sure that your tree includes documentation for any modified or
63 
+new features, syntax or semantic changes. Instructions for building
64 
+the docs are in ``docs/README.md``
65 
+
66 
+### 6. Commit and create a pull request to the "release" branch
61 67
62 68 
 ```bash
63 69 
 git add CHANGELOG.md
... ... 
@@ -65,9 +71,9 @@ git commit -m "Bump version to $VERSION"
65 65 
 git push origin bump_$VERSION
66 66 
 ```
67 67
68 
-### 6. Get 2 other maintainers to validate the pull request
68 
+### 7. Get 2 other maintainers to validate the pull request
69 69
70 
-### 7. Merge the pull request and apply tags
70 
+### 8. Merge the pull request and apply tags
71 71
72 72 
 ```bash
73 73 
 git checkout release
... ... 
@@ -78,7 +84,13 @@ git push
78 78 
 git push --tags
79 79 
 ```
80 80
81 
-### 8. Publish binaries
81 
+Merging the pull request to the release branch will automatically
82 
+update the documentation on the "latest" revision of the docs. You
83 
+should see the updated docs 5-10 minutes after the merge. The docs
84 
+will appear on http://docs.docker.io/. For more information about
85 
+documentation releases, see ``docs/README.md``
86 
+
87 
+### 9. Publish binaries
82 88
83 89 
 To run this you will need access to the release credentials.
84 90 
 Get them from [the infrastructure maintainers](
... ... 
@@ -100,6 +112,6 @@ use get-nightly.docker.io for general testing, and once everything is fine,
100 100 
 switch to get.docker.io).
101 101
102 102
103 
-### 9. Rejoice!
103 
+### 10. Rejoice!
104 104
105 105 
 Congratulations! You're done.