Guest24897
/
DockerCLI
mirror of https://github.com/docker/cli.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

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
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

74
docs/README.md
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
----------------------------------
@ -87,7 +83,7 @@ Publishing Documentation
------------------------
To publish a copy of the documentation you need a ``docs/awsconfig``
file containing AWS settings to deploy to. The release script will
file containing AWS settings to deploy to. The release script will
create an s3 if needed, and will then push the files to it.
```
@ -97,7 +93,7 @@ aws_secret_access_key = OIUYSADJHLKUHQWIUHE......
region = ap-southeast-2
```
The ``profile`` name must be the same as the name of the bucket you are
The ``profile`` name must be the same as the name of the bucket you are
deploying to - which you call from the docker directory:
``make AWS_S3_BUCKET=dowideit-docs docs-release``