From eecd9e7003d3cb2ec6921db327ab2a49b0e12253 Mon Sep 17 00:00:00 2001 From: Sven Dowideit Date: Wed, 8 Oct 2014 11:44:01 +1000 Subject: [PATCH] Mention the mkdocs.yml file for adding new documents and move the complicated discussion about branches lower down, hopefully most won't need to know Signed-off-by: Sven Dowideit Docker-DCO-1.1-Signed-off-by: Sven Dowideit (github: SvenDowideit) --- docs/README.md | 56 +++++++++++++++++++++++++++++--------------------- 1 file changed, 33 insertions(+), 23 deletions(-) diff --git a/docs/README.md b/docs/README.md index afcc1451a4..27ed7eef11 100755 --- a/docs/README.md +++ b/docs/README.md @@ -9,28 +9,6 @@ GitHub](https://github.com/docker/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 documentation 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. - -Also, now that we have a `docs` branch, we can keep the -[http://docs.docker.com](http://docs.docker.com) docs up to date with any bugs -found between Docker code releases. - -**Warning**: When *reading* the docs, the -[http://docs-stage.docker.com](http://docs-stage.docker.com) 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.com` (which points to the `docs` branch`) should be used for the -latest official release. - ## Contributing - Follow the contribution guidelines ([see @@ -46,11 +24,21 @@ changes. In the root of the `docker` source directory: - make docs + $ make docs + .... (lots of output) .... + $ docker run --rm -it -e AWS_S3_BUCKET -p 8000:8000 "docker-docs:master" mkdocs serve + Running at: http://0.0.0.0:8000/ + Live reload enabled. + Hold ctrl+c to quit. If you have any issues you need to debug, you can use `make docs-shell` and then run `mkdocs serve` +## Adding a new document + +New document (`.md`) files are added to the documentation builds by adding them +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 @@ -83,6 +71,28 @@ 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) +## 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` +branch, and send a PR against `master`. + +That way your edits 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. + +Also, now that we have a `docs` branch, we can keep the +[http://docs.docker.com](http://docs.docker.com) docs up to date with any bugs +found between Docker code releases. + +> **Warning**: When *reading* the docs, the +> [http://docs-stage.docker.com](http://docs-stage.docker.com) 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.com` (which points to the `docs` branch`) should be used for the +> latest official release. + ## Publishing Documentation To publish a copy of the documentation you need to have Docker up and running on your