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

Add a mention of 80 column lines and reflow the document to hide the 

evidence.

Docker-DCO-1.1-Signed-off-by: SvenDowideit <SvenDowideit@home.org.au> (github: SvenDowideit)
This commit is contained in:
SvenDowideit 2014-05-14 10:22:55 +10:00 committed by Tibor Vass
parent 91667137f0
commit 93ee19119b
1 changed files with 50 additions and 50 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

100
docs/README.md
View File

@ -1,37 +1,35 @@
# Docker Documentation # Docker Documentation
The source for Docker documentation is here under `sources/` and uses The source for Docker documentation is here under `sources/` and uses extended
extended Markdown, as implemented by [mkdocs](http://mkdocs.org). Markdown, as implemented by [mkdocs](http://mkdocs.org).
The HTML files are built and hosted on `https://docs.docker.io`, and The HTML files are built and hosted on `https://docs.docker.io`, and update
update automatically after each change to the master or release branch automatically after each change to the master or release branch of [Docker on
of [Docker on GitHub](https://github.com/dotcloud/docker) GitHub](https://github.com/dotcloud/docker) thanks to post-commit hooks. The
thanks to post-commit hooks. The "docs" branch maps to the "latest" "docs" branch maps to the "latest" documentation and the "master" (unreleased
documentation and the "master" (unreleased development) branch maps to development) branch maps to the "master" 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`
`docs` branch. You should always edit documentation on a local branch branch. You should always edit documentation on a local branch of the `master`
of the `master` branch, and send a PR against `master`. branch, and send a PR against `master`.
That way your fixes will automatically get included in later releases, That way your fixes will automatically get included in later releases, and docs
and docs maintainers can easily cherry-pick your changes into the maintainers can easily cherry-pick your changes into the `docs` release branch.
`docs` release branch. In the rare case where your change is not In the rare case where your change is not forward-compatible, you may need to
forward-compatible, you may need to base your changes on the `docs` base your changes on the `docs` branch.
branch.
Also, now that we have a `docs` branch, we can keep the 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 [http://docs.docker.io](http://docs.docker.io) docs up to date with any bugs
bugs found between `docker` code releases. found between `docker` code releases.
**Warning**: When *reading* the docs, the **Warning**: When *reading* the docs, the
[http://beta-docs.docker.io](http://beta-docs.docker.io) documentation [http://beta-docs.docker.io](http://beta-docs.docker.io) documentation may
may include features not yet part of any official docker release. The include features not yet part of any official docker release. The `beta-docs`
`beta-docs` site should be used only for understanding bleeding-edge site should be used only for understanding bleeding-edge development and
development and `docs.docker.io` (which points to the `docs` `docs.docker.io` (which points to the `docs` branch`) should be used for the
branch`) should be used for the latest official release. latest official release.
## Contributing ## Contributing
@ -41,59 +39,61 @@ branch`) should be used for the latest official release.
## Getting Started ## Getting Started
Docker documentation builds are done in a Docker container, which Docker documentation builds are done in a Docker container, which installs all
installs all the required tools, adds the local `docs/` directory and the required tools, adds the local `docs/` directory and builds the HTML docs.
builds the HTML docs. It then starts a HTTP server on port 8000 so that It then starts a HTTP server on port 8000 so that you can connect and see your
you can connect and see your changes. changes.
In the root of the `docker` source directory: In the root of the `docker` source directory:
make docs 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
then run `mkdocs serve` run `mkdocs serve`
## Style guide
The documentation is written with paragraphs wrapped at 80 colum lines to make
it easier for terminal use.
### Examples ### Examples
When writing examples give the user hints by making them resemble what When writing examples give the user hints by making them resemble what they see
they see in their shell: in their shell:
- Indent shell examples by 4 spaces so they get rendered as code. - Indent shell examples by 4 spaces so they get rendered as code.
- Start typed commands with `$ ` (dollar space), so that they are easily - Start typed commands with `$ ` (dollar space), so that they are easily
differentiated from program output. differentiated from program output.
- Program output has no prefix. - Program output has no prefix.
- Comments begin with `# ` (hash space). - Comments begin with `# ` (hash space).
- In-container shell commands begin with `$$ ` (dollar dollar space). - In-container shell commands begin with `$$ ` (dollar dollar space).
### Images ### Images
When you need to add images, try to make them as small as possible When you need to add images, try to make them as small as possible (e.g. as
(e.g. as gifs). Usually images should go in the same directory as the gifs). Usually images should go in the same directory as the `.md` file which
`.md` file which references them, or in a subdirectory if one already references them, or in a subdirectory if one already exists.
exists.
## Working using GitHub's file editor ## Working using GitHub's file editor
Alternatively, for small changes and typos you might want to use Alternatively, for small changes and typos you might want to use GitHub's built
GitHub's built in file editor. It allows you to preview your changes in file editor. It allows you to preview your changes right on-line (though
right on-line (though there can be some differences between GitHub there can be some differences between GitHub Markdown and [MkDocs
Markdown and [MkDocs Markdown](http://www.mkdocs.org/user-guide/writing-your-docs/)). Markdown](http://www.mkdocs.org/user-guide/writing-your-docs/)). Just be
Just be careful not to create many commits. And you must still careful not to create many commits. And you must still [sign your
[sign your work!](../CONTRIBUTING.md#sign-your-work) work!](../CONTRIBUTING.md#sign-your-work)
## Publishing Documentation ## 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` To make life
file containing AWS settings to deploy to. The release script will easier for 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.
[profile dowideit-docs] [profile dowideit-docs] aws_access_key_id = IHOIUAHSIDH234rwf....
aws_access_key_id = IHOIUAHSIDH234rwf.... aws_secret_access_key = OIUYSADJHLKUHQWIUHE...... region = ap-southeast-2
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
deploying to - which you call from the `docker` directory: to - which you call from the `docker` directory:
make AWS_S3_BUCKET=dowideit-docs docs-release make AWS_S3_BUCKET=dowideit-docs docs-release