mirror of https://github.com/docker/cli.git
Adds new Docs Style Guide.
Includes changes to mkdocs yml and removes style info from docs Read Me, adding a link instead. Docker-DCO-1.1-Signed-off-by: Fred Lifton <fred.lifton@docker.com> (github: fredlf) Conflicts: docs/README.md Revisions to style guide based on review. Docker-DCO-1.1-Signed-off-by: Fred Lifton <fred.lifton@docker.com> (github: fredlf) More Style Guide revisions based on review. Docker-DCO-1.1-Signed-off-by: Fred Lifton <fred.lifton@docker.com> (github: fredlf) A few more style guide copy edits Docker-DCO-1.1-Signed-off-by: Fred Lifton <fred.lifton@docker.com> (github: fredlf)
This commit is contained in:
parent
d83b068933
commit
c90e4b1bc5
|
@ -11,9 +11,8 @@ development) branch maps to the "master" documentation.
|
|||
|
||||
## Contributing
|
||||
|
||||
- Follow the contribution guidelines ([see
|
||||
`../CONTRIBUTING.md`](../CONTRIBUTING.md)).
|
||||
- [Remember to sign your work!](../CONTRIBUTING.md#sign-your-work)
|
||||
Be sure to follow the [contribution guidelines](../CONTRIBUTING.md)).
|
||||
In particular, [remember to sign your work!](../CONTRIBUTING.md#sign-your-work)
|
||||
|
||||
## Getting Started
|
||||
|
||||
|
@ -41,26 +40,10 @@ to the menu definition in the `docs/mkdocs.yml` file.
|
|||
|
||||
## Style guide
|
||||
|
||||
The documentation is written with paragraphs wrapped at 80 column lines to make
|
||||
it easier for terminal use.
|
||||
|
||||
### Examples
|
||||
|
||||
When writing examples, give the user hints by making them resemble what they see
|
||||
in their shell:
|
||||
|
||||
- Indent shell examples by 4 spaces so they get rendered as code.
|
||||
- Start typed commands with `$ ` (dollar space), so that they are easily
|
||||
differentiated from program output.
|
||||
- Program output has no prefix.
|
||||
- Comments begin with `# ` (hash space).
|
||||
- In-container shell commands begin with `$$ ` (dollar dollar space).
|
||||
|
||||
### Images
|
||||
|
||||
When you need to add images, try to make them as small as possible (e.g., as
|
||||
gifs). Usually images should go in the same directory as the `.md` file which
|
||||
references them, or in a subdirectory if one already exists.
|
||||
If you have questions about how to write for Docker's documentation (e.g.,
|
||||
questions about grammar, syntax, formatting, styling, language, or tone) please
|
||||
see the [style guide](sources/contributing/docs_style-guide.md). If something
|
||||
isn't clear in the guide, please submit a PR to help us improve it.
|
||||
|
||||
## Working using GitHub's file editor
|
||||
|
||||
|
@ -73,11 +56,11 @@ work!](../CONTRIBUTING.md#sign-your-work)
|
|||
|
||||
## Branches
|
||||
|
||||
**There are two branches related to editing docs**: `master` and a `docs`
|
||||
branch. You should always edit the documentation on a local branch of the `master`
|
||||
**There are two branches related to editing docs**: `master` and `docs`. You
|
||||
should always edit the documentation on a local branch of the `master`
|
||||
branch, and send a PR against `master`.
|
||||
|
||||
That way your edits will automatically get included in later releases, and docs
|
||||
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.
|
||||
|
@ -95,8 +78,10 @@ found between Docker code releases.
|
|||
|
||||
## Publishing Documentation
|
||||
|
||||
To publish a copy of the documentation you need to have Docker up and running on your
|
||||
machine. You'll also need a `docs/awsconfig` file containing AWS settings to deploy to.
|
||||
To publish a copy of the documentation you need to have Docker up and running on
|
||||
your machine. You'll also need a `docs/awsconfig` file containing the settings
|
||||
you need to access the AWS bucket you'll be deploying to.
|
||||
|
||||
The release script will create an s3 if needed, and will then push the files to it.
|
||||
|
||||
[profile dowideit-docs] aws_access_key_id = IHOIUAHSIDH234rwf....
|
||||
|
@ -115,7 +100,8 @@ also update the root docs pages by running
|
|||
|
||||
make AWS_S3_BUCKET=dowideit-docs BUILD_ROOT=yes docs-release
|
||||
|
||||
> **Note:** if you are using Boot2Docker on OSX and the above command returns an error,
|
||||
> **Note:**
|
||||
> if you are using Boot2Docker on OSX and the above command returns an error,
|
||||
> `Post http:///var/run/docker.sock/build?rm=1&t=docker-docs%3Apost-1.2.0-docs_update-2:
|
||||
> dial unix /var/run/docker.sock: no such file or directory', you need to set the Docker
|
||||
> host. Run `$(boot2docker shellinit)` to see the correct variable to set. The command
|
||||
|
|
Loading…
Reference in New Issue