From 83c5ea4b475e71aa053aa41a7b0d749d6f797e76 Mon Sep 17 00:00:00 2001 From: Andy Rothfusz Date: Tue, 18 Feb 2014 19:21:12 -0800 Subject: [PATCH 1/2] Update the documentation docs with new branch information. Docker-DCO-1.1-Signed-off-by: Andy Rothfusz (github: metalivedev) Upstream-commit: 05c692d64ec9cabe6c16385300405406ebe63f40 Component: engine --- components/engine/docs/README.md | 63 +++++++++++++++++++++++++------- 1 file changed, 50 insertions(+), 13 deletions(-) diff --git a/components/engine/docs/README.md b/components/engine/docs/README.md index 3fdbad2ead..71b3a09995 100644 --- a/components/engine/docs/README.md +++ b/components/engine/docs/README.md @@ -19,10 +19,24 @@ 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. +## Branches + +**There are two branches related to editing docs**: ``master`` and a +``doc*`` branch (currently ``doc0.8.1``). You should normally edit +docs on the ``master`` branch. That way your fixes will automatically +get included in later releases, and docs maintainers can easily +cherry-pick your changes to bring over to the current docs branch. In +the rare case where your change is not forward-compatible, then you +could base your change on the appropriate ``doc*`` branch. + +Now that we have a ``doc*`` branch, we can keep the ``latest`` docs +up to date with any bugs found between ``docker`` code releases. + +**Warning**: When *reading* the docs, 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`` (which points to the ``doc*`` +branch``) 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 @@ -39,7 +53,7 @@ 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 +### Native Installation Install dependencies from `requirements.txt` file in your `docker/docs` directory: @@ -48,7 +62,7 @@ directory: * Mac OS X: `[sudo] pip-2.7 install -r docs/requirements.txt` -###Alternative Installation: Docker Container +### Alternative Installation: Docker Container If you're running ``docker`` on your development machine then you may 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 In the ``docker`` source directory, run: ```make docs``` -This is the equivalent to ``make clean server`` since each container starts clean. +This is the equivalent to ``make clean server`` since each container +starts clean. -Usage ------ -* Follow the contribution guidelines (``../CONTRIBUTING.md``) +# Contributing + +## Normal Case: + +* Follow the contribution guidelines ([see + ``../CONTRIBUTING.md``](../CONTRIBUTING)). +* Remember to sign your work! * 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. @@ -75,6 +94,20 @@ Usage ``make clean docs`` must complete without any warnings or errors. +## Special Case for RST Newbies: + +If you want to write a new doc or make substantial changes to an +existing doc, but **you don't know RST syntax**, we will accept pull +requests in Markdown and plain text formats. We really want to +encourage people to share their knowledge and don't want the markup +syntax to be the obstacle. So when you make the Pull Request, please +note in your comment that you need RST markup assistance, and we'll +make the changes for you, and then we will make a pull request to your +pull request so that you can get all the changes and learn about the +markup. You still need to follow the +[``CONTRIBUTING``](../CONTRIBUTING) guidelines, so please sign your +commits. + Working using GitHub's file editor ---------------------------------- @@ -93,8 +126,11 @@ exists. 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`` + +* 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 ---------------------- @@ -106,7 +142,8 @@ Guides on using sphinx Hello world =========== - This is.. (etc.) + This is a reference to :ref:`hello_world` and will work even if we + move the target to another file or change the title of the section. ``` The ``_hello_world:`` will make it possible to link to this position From 98d4bbe0f67907e4757ba43a771ddaa73c138df9 Mon Sep 17 00:00:00 2001 From: Andy Rothfusz Date: Tue, 18 Feb 2014 19:25:43 -0800 Subject: [PATCH 2/2] update links Docker-DCO-1.1-Signed-off-by: Andy Rothfusz (github: metalivedev) Upstream-commit: 196702fbf9905426e590c0dbcb6101e72c62aac6 Component: engine --- components/engine/docs/README.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/components/engine/docs/README.md b/components/engine/docs/README.md index 71b3a09995..9379d86870 100644 --- a/components/engine/docs/README.md +++ b/components/engine/docs/README.md @@ -81,8 +81,8 @@ starts clean. ## Normal Case: * Follow the contribution guidelines ([see - ``../CONTRIBUTING.md``](../CONTRIBUTING)). -* Remember to sign your work! + ``../CONTRIBUTING.md``](../CONTRIBUTING.md)). +* [Remember to sign your work!](../CONTRIBUTING.md#sign-your-work) * 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. @@ -115,6 +115,7 @@ 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. +And you must still [sign your work!](../CONTRIBUTING.md#sign-your-work) Images ------