1
0
Fork 0
mirror of https://github.com/moby/moby.git synced 2022-11-09 12:21:53 -05:00
moby--moby/docs
Sven Dowideit ebaff50bd2 for want of a comma, the kingdom was lost
Docker-DCO-1.1-Signed-off-by: Sven Dowideit <SvenDowideit@fosiki.com> (github: SvenDowideit)
2014-04-30 10:12:21 +10:00
..
sources Update working-with-docker.md 2014-04-29 13:49:36 -07:00
theme Merge pull request #5440 from ostezer/docs-improve-code-block-rendering 2014-04-30 00:45:04 +03:00
asciinema.patch move the documentation to markdown 2014-04-16 11:04:01 +10:00
convert.sh move the documentation to markdown 2014-04-16 11:04:01 +10:00
convert_with_sphinx.patch move the documentation to markdown 2014-04-16 11:04:01 +10:00
Dockerfile make the non-release doc warning conditional and add version info 2014-04-23 21:07:12 +10:00
MAINTAINERS Adding myself to the MAINTAINERS file. 2014-04-16 00:33:14 +03:00
Makefile Switch sphinx man_pages generation to use commandline/cli instead of toctree for a more relevant/useful man page 2013-11-19 10:10:42 -07:00
mkdocs.yml Addressed regression of private repository documentation. 2014-04-28 16:08:55 -04:00
pr4923.patch move the documentation to markdown 2014-04-16 11:04:01 +10:00
README.md Replaced all double backticks in README with singles 2014-04-26 10:12:09 -04:00
release.sh move the documentation to markdown 2014-04-16 11:04:01 +10:00
requirements.txt Fix Travis build errors by bumping our python module versions to be newer 2014-01-20 12:30:18 -07:00
s3_website.json for want of a comma, the kingdom was lost 2014-04-30 10:12:21 +10:00

Docker Documentation

Overview

The source for Docker documentation is here under sources/ and uses extended Markdown, as implemented by mkdocs.

The HTML files are built and hosted on https://docs.docker.io, and update automatically after each change to the master or release branch of Docker on GitHub 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.io docs up to date with any bugs found between docker code releases.

Warning: When reading the docs, the 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.

Getting Started

Docker documentation builds are done in a Docker container, which installs all the required tools, adds the local docs/ directory and builds the HTML docs. It then starts a HTTP server on port 8000 so that 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

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). Just be careful not to create many commits. And you must still sign your work!

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

To publish a copy of the documentation you need a docs/awsconfig file containing AWS settings to deploy 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....
aws_secret_access_key = OIUYSADJHLKUHQWIUHE......
region = ap-southeast-2

The profile name must be the same as the name of the bucket you are deploying to - which you call from the docker directory:

make AWS_S3_BUCKET=dowideit-docs docs-release