commit
3b279d0218
|
@ -7,64 +7,60 @@ Overview
|
||||||
The source for Docker documentation is here under ``sources/`` and uses
|
The source for Docker documentation is here under ``sources/`` and uses
|
||||||
extended Markdown, as implemented by [mkdocs](http://mkdocs.org).
|
extended Markdown, as implemented by [mkdocs](http://mkdocs.org).
|
||||||
|
|
||||||
The HTML files are built and hosted on https://docs.docker.io, and update
|
The HTML files are built and hosted on `https://docs.docker.io`, and
|
||||||
automatically after each change to the master or release branch of the
|
update automatically after each change to the master or release branch
|
||||||
[docker files on GitHub](https://github.com/dotcloud/docker) thanks to
|
of [Docker on GitHub](https://github.com/dotcloud/docker)
|
||||||
post-commit hooks. The "release" branch maps to the "latest"
|
thanks to post-commit hooks. The "docs" branch maps to the "latest"
|
||||||
documentation and the "master" (unreleased development) branch maps to the "master"
|
documentation and the "master" (unreleased development) branch maps to
|
||||||
documentation.
|
the "master" documentation.
|
||||||
|
|
||||||
## Branches
|
## Branches
|
||||||
|
|
||||||
**There are two branches related to editing docs**: ``master`` and a
|
**There are two branches related to editing docs**: ``master`` and a
|
||||||
``docs`` branch. You should always edit
|
``docs`` branch. You should always edit documentation on a local branch
|
||||||
docs on a local branch of the ``master`` branch, and send a PR against ``master``.
|
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.
|
|
||||||
|
|
||||||
Now that we have a ``docs`` branch, we can keep the [http://docs.docker.io](http://docs.docker.io) docs
|
That way your fixes will automatically get included in later releases,
|
||||||
up to date with any bugs found between ``docker`` code 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
|
Also, now that we have a ``docs`` branch, we can keep the
|
||||||
include features not yet part of any official docker
|
[http://docs.docker.io](http://docs.docker.io) docs up to date with any
|
||||||
release. The ``beta-docs`` site should be used only for understanding
|
bugs found between ``docker`` code releases.
|
||||||
bleeding-edge development and ``docs.docker.io`` (which points to the ``docs``
|
|
||||||
|
**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.
|
branch``) should be used for the latest official release.
|
||||||
|
|
||||||
Getting Started
|
Getting Started
|
||||||
---------------
|
---------------
|
||||||
|
|
||||||
Docker documentation builds are done in a docker container, which installs all
|
Docker documentation builds are done in a Docker container, which
|
||||||
the required tools, adds the local ``docs/`` directory and builds the HTML
|
installs all the required tools, adds the local ``docs/`` directory and
|
||||||
docs. It then starts a HTTP server on port 8000 so that you can connect
|
builds the HTML docs. It then starts a HTTP server on port 8000 so that
|
||||||
and see your changes.
|
you can connect and see your changes.
|
||||||
|
|
||||||
In the ``docker`` source directory, run:
|
In the root of the ``docker`` source directory:
|
||||||
```make docs```
|
|
||||||
|
cd docker
|
||||||
|
|
||||||
|
Run:
|
||||||
|
|
||||||
|
make docs
|
||||||
|
|
||||||
If you have any issues you need to debug, you can use ``make docs-shell`` and
|
If you have any issues you need to debug, you can use ``make docs-shell`` and
|
||||||
then run ``mkdocs serve``
|
then run ``mkdocs serve``
|
||||||
|
|
||||||
# Contributing
|
# Contributing
|
||||||
|
|
||||||
## Normal Case:
|
|
||||||
|
|
||||||
* Follow the contribution guidelines ([see
|
* Follow the contribution guidelines ([see
|
||||||
``../CONTRIBUTING.md``](../CONTRIBUTING.md)).
|
``../CONTRIBUTING.md``](../CONTRIBUTING.md)).
|
||||||
* [Remember to sign your work!](../CONTRIBUTING.md#sign-your-work)
|
* [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
|
Working using GitHub's file editor
|
||||||
----------------------------------
|
----------------------------------
|
||||||
|
@ -87,7 +83,7 @@ Publishing Documentation
|
||||||
------------------------
|
------------------------
|
||||||
|
|
||||||
To publish a copy of the documentation you need a ``docs/awsconfig``
|
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.
|
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
|
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:
|
deploying to - which you call from the docker directory:
|
||||||
|
|
||||||
``make AWS_S3_BUCKET=dowideit-docs docs-release``
|
``make AWS_S3_BUCKET=dowideit-docs docs-release``
|
||||||
|
|
Loading…
Reference in New Issue