README.md
1Docker documentation and website
2================================
3
4Documentation
5-------------
6This is your definite place to contribute to the docker documentation. The documentation is generated from the
7.rst files under sources.
8
9The folder also contains the other files to create the http://docker.io website, but you can generally ignore
10most of those.
11
12
13Installation
14------------
15
16* Work in your own fork of the code, we accept pull requests.
17* Install sphinx: `pip install sphinx`
18 * Mac OS X: `[sudo] pip-2.7 install sphinx`)
19* Install sphinx httpdomain contrib package: `pip install sphinxcontrib-httpdomain`
20 * Mac OS X: `[sudo] pip-2.7 install sphinxcontrib-httpdomain`
21* If pip is not available you can probably install it using your favorite package manager as **python-pip**
22
23Usage
24-----
25* Change the `.rst` files with your favorite editor to your liking.
26* Run `make docs` to clean up old files and generate new ones.
27* Your static website can now be found in the `_build` directory.
28* To preview what you have generated run `make server` and open <http://localhost:8000/> in your favorite browser.
29
30Working using GitHub's file editor
31----------------------------------
32Alternatively, for small changes and typo's you might want to use GitHub's built in file editor. It allows
33you to preview your changes right online. Just be carefull not to create many commits.
34
35Images
36------
37When you need to add images, try to make them as small as possible (e.g. as gif).
38
39
40Notes
41-----
42* The index.html and gettingstarted.html files are copied from the source dir to the output dir without modification.
43So changes to those pages should be made directly in html
44* For the template the css is compiled from less. When changes are needed they can be compiled using
45lessc ``lessc main.less`` or watched using watch-lessc ``watch-lessc -i main.less -o main.css``
46
47
48Guides on using sphinx
49----------------------
50* To make links to certain pages create a link target like so:
51
52 ```
53 .. _hello_world:
54
55 Hello world
56 ===========
57
58 This is.. (etc.)
59 ```
60
61 The ``_hello_world:`` will make it possible to link to this position (page and marker) from all other pages.
62
63* Notes, warnings and alarms
64
65 ```
66 # a note (use when something is important)
67 .. note::
68
69 # a warning (orange)
70 .. warning::
71
72 # danger (red, use sparsely)
73 .. danger::
74
75* Code examples
76
77 Start without $, so it's easy to copy and paste.
78