|
|
@@ -1,8 +1,4 @@
|
|
|
-Docker Documentation
|
|
|
-====================
|
|
|
-
|
|
|
-Overview
|
|
|
---------
|
|
|
+# Docker Documentation
|
|
|
|
|
|
The source for Docker documentation is here under `sources/` and uses
|
|
|
extended Markdown, as implemented by [mkdocs](http://mkdocs.org).
|
|
|
@@ -37,8 +33,13 @@ may include features not yet part of any official docker release. The
|
|
|
development and `docs.docker.io` (which points to the `docs`
|
|
|
branch`) should be used for the latest official release.
|
|
|
|
|
|
-Getting Started
|
|
|
----------------
|
|
|
+## Contributing
|
|
|
+
|
|
|
+- Follow the contribution guidelines ([see
|
|
|
+ `../CONTRIBUTING.md`](../CONTRIBUTING.md)).
|
|
|
+- [Remember to sign your work!](../CONTRIBUTING.md#sign-your-work)
|
|
|
+
|
|
|
+## Getting Started
|
|
|
|
|
|
Docker documentation builds are done in a Docker container, which
|
|
|
installs all the required tools, adds the local `docs/` directory and
|
|
|
@@ -47,40 +48,40 @@ you can connect and see your changes.
|
|
|
|
|
|
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
|
|
|
-
|
|
|
-* Follow the contribution guidelines ([see
|
|
|
- `../CONTRIBUTING.md`](../CONTRIBUTING.md)).
|
|
|
-* [Remember to sign your work!](../CONTRIBUTING.md#sign-your-work)
|
|
|
+### Examples
|
|
|
|
|
|
-Working using GitHub's file editor
|
|
|
-----------------------------------
|
|
|
+When writing examples give the user hints by making them resemble what
|
|
|
+they see in their shell:
|
|
|
|
|
|
-Alternatively, for small changes and typos you might want to use
|
|
|
-GitHub's built in file editor. It allows you to preview your changes
|
|
|
-right on-line (though there can be some differences between GitHub
|
|
|
-Markdown and mkdocs Markdown). Just be careful not to create many commits.
|
|
|
-And you must still [sign your work!](../CONTRIBUTING.md#sign-your-work)
|
|
|
+- 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
|
|
|
-------
|
|
|
+### 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.
|
|
|
|
|
|
-Publishing Documentation
|
|
|
-------------------------
|
|
|
+## Working using GitHub's file editor
|
|
|
+
|
|
|
+Alternatively, for small changes and typos you might want to use
|
|
|
+GitHub's built in file editor. It allows you to preview your changes
|
|
|
+right on-line (though there can be some differences between GitHub
|
|
|
+Markdown and [MkDocs Markdown](http://www.mkdocs.org/user-guide/writing-your-docs/)).
|
|
|
+Just be careful not to create many commits. And you must still
|
|
|
+[sign your work!](../CONTRIBUTING.md#sign-your-work)
|
|
|
+
|
|
|
+## 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
|
O.S. Tezer