1. docker
  2. Commit 05c692d64ec9cabe6c16385300405406ebe63f40
Browse code

Update the documentation docs with new branch information. Docker-DCO-1.1-Signed-off-by: Andy Rothfusz <github@developersupport.net> (github: metalivedev)

Andy Rothfusz authored on 2014/02/19 12:21:12
Showing 1 changed files
docs/README.md
History View file @ 05c692d
... ... 
@@ -19,10 +19,24 @@ post-commit hooks. The "release" branch maps to the "latest"
19 19 
 documentation and the "master" branch maps to the "master"
20 20 
 documentation.
21 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.
22 
+## Branches
23 
+
24 
+**There are two branches related to editing docs**: ``master`` and a
25 
+``doc*`` branch (currently ``doc0.8.1``). You should normally edit
26 
+docs on the ``master`` branch. That way your fixes will automatically
27 
+get included in later releases, and docs maintainers can easily
28 
+cherry-pick your changes to bring over to the current docs branch. In
29 
+the rare case where your change is not forward-compatible, then you
30 
+could base your change on the appropriate ``doc*`` branch.
31 
+
32 
+Now that we have a ``doc*`` branch, we can keep the ``latest`` docs
33 
+up to date with any bugs found between ``docker`` code releases.
34 
+
35 
+**Warning**: When *reading* the docs, the ``master`` documentation may
36 
+include features not yet part of any official docker
37 
+release. ``Master`` docs should be used only for understanding
38 
+bleeding-edge development and ``latest`` (which points to the ``doc*``
39 
+branch``) should be used for the latest official release.
26 40
27 41 
 If you need to manually trigger a build of an existing branch, then
28 42 
 you can do that through the [readthedocs
... ... 
@@ -39,7 +53,7 @@ Getting Started
39 39 
 To edit and test the docs, you'll need to install the Sphinx tool and
40 40 
 its dependencies. There are two main ways to install this tool:
41 41
42 
-###Native Installation
42 
+### Native Installation
43 43
44 44 
 Install dependencies from `requirements.txt` file in your `docker/docs`
45 45 
 directory:
... ... 
@@ -48,7 +62,7 @@ directory:
48 48
49 49 
 * Mac OS X: `[sudo] pip-2.7 install -r docs/requirements.txt`
50 50
51 
-###Alternative Installation: Docker Container
51 
+### Alternative Installation: Docker Container
52 52
53 53 
 If you're running ``docker`` on your development machine then you may
54 54 
 find it easier and cleaner to use the docs Dockerfile. This installs Sphinx
... ... 
@@ -59,11 +73,16 @@ docs inside the container, even starting a simple HTTP server on port
59 59 
 In the ``docker`` source directory, run:
60 60 
     ```make docs```
61 61
62 
-This is the equivalent to ``make clean server`` since each container starts clean.
62 
+This is the equivalent to ``make clean server`` since each container
63 
+starts clean.
63 64
64 
-Usage
65 
-* Follow the contribution guidelines (``../CONTRIBUTING.md``)
65 
+# Contributing
66 
+
67 
+## Normal Case:
68 
+
69 
+* Follow the contribution guidelines ([see
70 
+  ``../CONTRIBUTING.md``](../CONTRIBUTING)).
71 
+* Remember to sign your work!
66 72 
 * Work in your own fork of the code, we accept pull requests.
67 73 
 * Change the ``.rst`` files with your favorite editor -- try to keep the
68 74 
   lines short and respect RST and Sphinx conventions.
... ... 
@@ -75,6 +94,20 @@ Usage
75 75
76 76 
 ``make clean docs`` must complete without any warnings or errors.
77 77
78 
+## Special Case for RST Newbies:
79 
+
80 
+If you want to write a new doc or make substantial changes to an
81 
+existing doc, but **you don't know RST syntax**, we will accept pull
82 
+requests in Markdown and plain text formats. We really want to
83 
+encourage people to share their knowledge and don't want the markup
84 
+syntax to be the obstacle. So when you make the Pull Request, please
85 
+note in your comment that you need RST markup assistance, and we'll
86 
+make the changes for you, and then we will make a pull request to your
87 
+pull request so that you can get all the changes and learn about the
88 
+markup. You still need to follow the
89 
+[``CONTRIBUTING``](../CONTRIBUTING) guidelines, so please sign your
90 
+commits.
91 
+
78 92 
 Working using GitHub's file editor
79 93 
 ----------------------------------
80 94
... ... 
@@ -93,8 +126,11 @@ exists.
93 93
94 94 
 Notes
95 95 
 -----
96 
-* For the template the css is compiled from less. When changes are needed they can be compiled using
97 
-lessc ``lessc main.less`` or watched using watch-lessc ``watch-lessc -i main.less -o main.css``
96 
+
97 
+* For the template the css is compiled from less. When changes are
98 
+  needed they can be compiled using
99 
+
100 
+  lessc ``lessc main.less`` or watched using watch-lessc ``watch-lessc -i main.less -o main.css``
98 101
99 102 
 Guides on using sphinx
100 103 
 ----------------------
... ... 
@@ -106,7 +142,8 @@ Guides on using sphinx
106 106 
     Hello world
107 107 
     ===========
108 108
109 
-    This is.. (etc.)
109 
+    This is a reference to :ref:`hello_world` and will work even if we
110 
+    move the target to another file or change the title of the section.
110 111 
   ```
111 112
112 113 
   The ``_hello_world:`` will make it possible to link to this position