Updated Docs README

Docker-DCO-1.1-Signed-off-by: James Turnbull <james@lovedthanlost.net> (github: jamtur01)
This commit is contained in:
James Turnbull 2014-04-26 08:10:19 -04:00 committed by Tibor Vass
parent 53eedfc835
commit 1e3f899705
1 changed files with 35 additions and 39 deletions

View File

@ -7,64 +7,60 @@ Overview
The source for Docker documentation is here under ``sources/`` and uses
extended Markdown, as implemented by [mkdocs](http://mkdocs.org).
The HTML files are built and hosted on https://docs.docker.io, and 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" (unreleased development) branch maps to the "master"
documentation.
The HTML files are built and hosted on `https://docs.docker.io`, and
update automatically after each change to the master or release branch
of [Docker on GitHub](https://github.com/dotcloud/docker)
thanks to post-commit hooks. The "docs" branch maps to the "latest"
documentation and the "master" (unreleased development) branch maps to
the "master" documentation.
## Branches
**There are two branches related to editing docs**: ``master`` and a
``docs`` branch. You should always edit
docs on a local branch of the ``master`` branch, and send a PR against ``master``.
That way your fixes
will automatically get included in later releases, and docs maintainers
can easily cherry-pick your changes into the ``docs`` release branch.
In the rare case where your change is not forward-compatible,
you may need to base your changes on the ``docs`` branch.
``docs`` branch. You should always edit documentation on a local branch
of the ``master`` branch, and send a PR against ``master``.
Now that we have a ``docs`` branch, we can keep the [http://docs.docker.io](http://docs.docker.io) docs
up to date with any bugs found between ``docker`` code releases.
That way your fixes will automatically get included in later releases,
and docs maintainers can easily cherry-pick your changes into the
``docs`` release branch. In the rare case where your change is not
forward-compatible, you may need to base your changes on the ``docs``
branch.
**Warning**: When *reading* the docs, the [http://beta-docs.docker.io](http://beta-docs.docker.io) documentation may
include features not yet part of any official docker
release. The ``beta-docs`` site should be used only for understanding
bleeding-edge development and ``docs.docker.io`` (which points to the ``docs``
Also, now that we have a ``docs`` branch, we can keep the
[http://docs.docker.io](http://docs.docker.io) docs up to date with any
bugs found between ``docker`` code releases.
**Warning**: When *reading* the docs, the
[http://beta-docs.docker.io](http://beta-docs.docker.io) documentation
may include features not yet part of any official docker release. The
``beta-docs`` site should be used only for understanding bleeding-edge
development and ``docs.docker.io`` (which points to the ``docs``
branch``) should be used for the latest official release.
Getting Started
---------------
Docker documentation builds are done in a docker container, which installs all
the required tools, adds the local ``docs/`` directory and builds the HTML
docs. It then starts a HTTP server on port 8000 so that you can connect
and see your changes.
Docker documentation builds are done in a Docker container, which
installs all the required tools, adds the local ``docs/`` directory and
builds the HTML docs. It then starts a HTTP server on port 8000 so that
you can connect and see your changes.
In the ``docker`` source directory, run:
```make docs```
In the root of the ``docker`` source directory:
cd docker
Run:
make docs
If you have any issues you need to debug, you can use ``make docs-shell`` and
then run ``mkdocs serve``
# Contributing
## Normal Case:
* Follow the contribution guidelines ([see
``../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 ``.md`` files with your favorite editor -- try to keep the
lines short (80 chars) and respect Markdown 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
----------------------------------