From 1749d99b3174063a0bb2bb71ed0aeb3a7d608a52 Mon Sep 17 00:00:00 2001 From: Mary Anthony Date: Wed, 5 Aug 2015 10:57:17 -0700 Subject: [PATCH] - Updating install docs fixes #1648 - Updating the Dockerfile to lastest - Adding support for building all the public doc projects from machine Signed-off-by: Mary Anthony Michael's comments Signed-off-by: Mary Anthony Adding in comments from nathan Signed-off-by: Mary Anthony --- docs/Dockerfile | 27 ++++++------- docs/README.md | 81 +++++++++++++++++++++++++++++++++++++++ docs/get-started.md | 2 +- docs/index.md | 2 +- docs/install-machine.md | 64 +++++++++---------------------- docs/pre-process.sh | 61 +++++++++++++++++++++++++++++ docs/reference/create.md | 5 ++- docs/reference/inspect.md | 1 + docs/reference/kill.md | 1 + docs/reference/restart.md | 1 + docs/reference/rm.md | 1 + docs/reference/start.md | 1 + docs/reference/stop.md | 1 + 13 files changed, 185 insertions(+), 63 deletions(-) create mode 100644 docs/README.md create mode 100755 docs/pre-process.sh diff --git a/docs/Dockerfile b/docs/Dockerfile index f993586075..bd009bbfa9 100644 --- a/docs/Dockerfile +++ b/docs/Dockerfile @@ -1,26 +1,27 @@ FROM docs/base:latest MAINTAINER Mary Anthony (@moxiegirl) -# to get the git info for this repo +# To get the git info for this repo COPY . /src COPY . /docs/content/machine/ +RUN svn checkout https://github.com/docker/compose/trunk/docs /docs/content/compose +RUN svn checkout https://github.com/docker/docker/trunk/docs /docs/content/docker +RUN svn checkout https://github.com/docker/swarm/trunk/docs /docs/content/swarm +RUN svn checkout https://github.com/docker/distribution/trunk/docs /docs/content/registry +RUN svn checkout https://github.com/docker/tutorials/trunk/docs /docs/content +RUN svn checkout https://github.com/docker/opensource/trunk/docs /docs/content/opensource +RUN svn checkout https://github.com/kitematic/kitematic/trunk/docs /docs/content/kitematic + + # Sed to process GitHub Markdown # 1-2 Remove comment code from metadata block # 3 Change ](/word to ](/project/ in links # 4 Change ](word.md) to ](/project/word) # 5 Remove .md extension from link text -# 6 Change ](./ to ](/project/word) -# 7 Change ](../../ to ](/project/ -# 8 Change ](../ to ](/project/ +# 6 Change ](../ to ](/project/word) +# 7 Change ](../../ to ](/project/ --> not implemented # -RUN find /docs/content/machine -type f -name "*.md" -exec sed -i.old \ - -e '/^/g' \ - -e '/^/g' \ - -e 's/\(\]\)\([(]\)\(\/\)/\1\2\/machine\//g' \ - -e 's/\(\][(]\)\([A-z].*\)\(\.md\)/\1\/machine\/\2/g' \ - -e 's/\([(]\)\(.*\)\(\.md\)/\1\2/g' \ - -e 's/\(\][(]\)\(\.\/\)/\1\/machine\//g' \ - -e 's/\(\][(]\)\(\.\.\/\.\.\/\)/\1\/machine\//g' \ - -e 's/\(\][(]\)\(\.\.\/\)/\1\/machine\//g' {} \; +# +RUN /src/pre-process.sh /docs diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000000..11afba721e --- /dev/null +++ b/docs/README.md @@ -0,0 +1,81 @@ +# Contributing to the Docker Compose documentation + +The documentation in this directory is part of the [this documentation](docs.docker.com). Docker uses [the Hugo static generator](http://gohugo.io/overview/introduction/) to convert project Markdown files to a static HTML site. + +You don't need to be a Hugo expert to contribute to the compose documentation. If you are familiar with Markdown, you can modify the content in the `docs` files. + +If you want to add a new file or change the location of the document in the menu, you do need to know a little more. If you want the detail of contributing, [use our contributor guide](http://docs.docker.com/project/make-a-contribution/). + +## Documentation contributing workflow + +1. Edit a Markdown file in the tree. + +2. Save your changes. + +3. Make sure all your changes maintain an 80 character line wrap. + + All check lines you've written. Don't wrap content you didn't change material. + +3. Make sure you are in the `docs` subdirectory. + +4. Build the documentation. + + $ make docs + ---> ffcf3f6c4e97 + Removing intermediate container a676414185e8 + Successfully built ffcf3f6c4e97 + docker run --rm -it -e AWS_S3_BUCKET -e NOCACHE -p 8000:8000 -e DOCKERHOST "docs-base:test-tooling" hugo server --port=8000 --baseUrl=192.168.59.103 --bind=0.0.0.0 + ERROR: 2015/06/13 MenuEntry's .Url is deprecated and will be removed in Hugo 0.15. Use .URL instead. + 0 of 4 drafts rendered + 0 future content + 12 pages created + 0 paginator pages created + 0 tags created + 0 categories created + in 55 ms + Serving pages from /docs/public + Web Server is available at http://0.0.0.0:8000/ + Press Ctrl+C to stop + +5. Open the available server in your browser. + + The documentation server has the complete menu but only the Docker Compose + documentation resolves. You can't access the other project docs from this + localized build. + +## Tips on Hugo metadata and menu positioning + +The top of each Docker Compose documentation file contains TOML metadata. The metadata is commented out to prevent it from appearing in GitHub. + + + +The metadata alone has this structure: + + +++ + title = "Extending services in Compose" + description = "How to use Docker Compose's extends keyword to share configuration between files and projects" + keywords = ["fig, composition, compose, docker, orchestration, documentation, docs"] + [menu.main] + parent="smn_workw_compose" + weight=2 + +++ + +The `[menu.main]` section refers to navigation defined [in the main Docker menu](https://github.com/docker/docs-base/blob/hugo/config.toml). This metadata says *add a menu item called* Extending services in Compose *to the menu with the* `smn_workdw_compose` *identifier*. If you locate the menu in the configuration, you'll find *Create multi-container applications* is the menu title. + +You can move an article in the tree by specifying a new parent. You can shift the location of the item by changing its weight. Higher numbers are heavier and shift the item to the bottom of menu. Low or no numbers shift it up. + + +## Other key documentation repositories + +The `docker/docs-base` repository contains [the Hugo theme and menu configuration](https://github.com/docker/docs-base). If you open the `Dockerfile` you'll see the `make docs` relies on this as a base image for building the Compose documentation. + +The `docker/docs.docker.com` repository contains [build system for building the Docker documentation site](https://github.com/docker/docs.docker.com). Fork this repository to build the entire documentation site. diff --git a/docs/get-started.md b/docs/get-started.md index e97824b86b..d528ebf1df 100644 --- a/docs/get-started.md +++ b/docs/get-started.md @@ -110,7 +110,7 @@ $ docker-machine ip dev 192.168.99.100 ``` -For instance, you can try running a webserver ([nginx](https://nginx.org)) in a +For instance, you can try running a webserver ([nginx](https://www.nginx.com/) in a container with the following command: ``` diff --git a/docs/index.md b/docs/index.md index f4a9405790..ce104f372f 100644 --- a/docs/index.md +++ b/docs/index.md @@ -60,7 +60,7 @@ like-minded individuals, we have a number of open channels for communication. Github](https://github.com/docker/machine/pulls). For more information and resources, please visit -[https://docs.docker.com/project/get-help/](https://docs.docker.com/project/get-help/). +[our help page](https://docs.docker.com/project/get-help/). ## Where to go next diff --git a/docs/install-machine.md b/docs/install-machine.md index 41a40d334c..772dcf9b2e 100644 --- a/docs/install-machine.md +++ b/docs/install-machine.md @@ -9,7 +9,7 @@ weight=3 +++ -## Install Docker Machine +# Install Docker Machine Docker Machine is supported on Windows, OS X, and Linux and is installable as one standalone binary. The links to the binaries for the various platforms and @@ -17,61 +17,33 @@ architectures are available at the [Github Release](https://github.com/docker/machine/releases/) page. -### OS X and Linux +## OS X and Windows -To install on OS X or Linux, download the proper binary to somewhere in your -`PATH` (e.g. `/usr/local/bin`) and make it executable. For instance, to install on -most OS X machines these commands should suffice: +Install Machine using the Docker Toolbox using the Mac OS X installation +instruction or Windows installation instructions. -``` -$ curl -L https://github.com/docker/machine/releases/download/v0.3.1/docker-machine_darwin-amd64 > /usr/local/bin/docker-machine -$ chmod +x /usr/local/bin/docker-machine -``` +## On Linux -For Linux, just substitute "linux" for "darwin" in the binary name above. +To install on Linux, do the following: -Now you should be able to check the version with `docker-machine -v`: +1. Install Docker version 1.7.1 or greater: -``` -$ docker-machine -v -machine version 0.3.1 -``` +2. Download the Machine binary to somewhere in your `PATH` (for example, `/usr/local/bin`). -In order to run Docker commands on your machines without having to use SSH, make -sure to install the Docker client as well, e.g.: + $ curl -L https://github.com/docker/machine/releases/download/v0.4.0/docker-machine_linux-amd64 > /usr/local/bin/docker-machine -``` -$ curl -L https://get.docker.com/builds/Darwin/x86_64/docker-latest > /usr/local/bin/docker -$ chmod +x /usr/local/bin/docker -``` +3. Apply executable permissions to the binary: -### Windows + $ chmod +x /usr/local/bin/docker-machine -Currently, Docker recommends that you install and use Docker Machine on Windows -with [msysgit](https://msysgit.github.io/). This will provide you with some -programs that Docker Machine relies on such as `ssh`, as well as a functioning -shell. +4. Check the installation by displaying the Machine version: -When you have installed msysgit, start up the terminal prompt and run the -following commands. Here it is assumed that you are on a 64-bit Windows -installation. If you are on a 32-bit installation, please substitute "i386" for -"x86_64" in the URLs mentioned. + $ docker-machine -v + machine version 0.4.0 -First, install the Docker client binary: +## Where to go next -``` -$ curl -L https://get.docker.com/builds/Windows/x86_64/docker-latest.exe > /bin/docker -``` +* [Docker Machine overview](/) +* [Docker Machine driver reference](/drivers) +* [Docker Machine subcommand reference](/reference) -Next, install the Docker Machine binary: - -``` -$ curl -L https://github.com/docker/machine/releases/download/v0.3.1/docker-machine_windows-amd64.exe > /bin/docker-machine -``` - -Now running `docker-machine` should work. - -``` -$ docker-machine -v -machine version 0.3.1 -``` diff --git a/docs/pre-process.sh b/docs/pre-process.sh new file mode 100755 index 0000000000..75e9611f2f --- /dev/null +++ b/docs/pre-process.sh @@ -0,0 +1,61 @@ +#!/bin/bash -e + +# Populate an array with just docker dirs and one with content dirs +docker_dir=(`ls -d /docs/content/docker/*`) +content_dir=(`ls -d /docs/content/*`) + +# Loop content not of docker/ +# +# Sed to process GitHub Markdown +# 1-2 Remove comment code from metadata block +# 3 Remove .md extension from link text +# 4 Change ](/ to ](/project/ in links +# 5 Change ](word) to ](/project/word) +# 6 Change ](../../ to ](/project/ +# 7 Change ](../ to ](/project/word) +# +for i in "${content_dir[@]}" +do + : + case $i in + "/docs/content/windows") + ;; + "/docs/content/mac") + ;; + "/docs/content/linux") + ;; + "/docs/content/docker") + y=${i##*/} + find $i -type f -name "*.md" -exec sed -i.old \ + -e '/^/g' \ + -e '/^/g' {} \; + ;; + *) + y=${i##*/} + find $i -type f -name "*.md" -exec sed -i.old \ + -e '/^/g' \ + -e '/^/g' \ + -e 's/\(\]\)\([(]\)\(\/\)/\1\2\/'$y'\//g' \ + -e 's/\(\][(]\)\([A-z].*\)\(\.md\)/\1\/'$y'\/\2/g' \ + -e 's/\([(]\)\(.*\)\(\.md\)/\1\2/g' \ + -e 's/\(\][(]\)\(\.\/\)/\1\/'$y'\//g' \ + -e 's/\(\][(]\)\(\.\.\/\.\.\/\)/\1\/'$y'\//g' \ + -e 's/\(\][(]\)\(\.\.\/\)/\1\/'$y'\//g' {} \; + ;; + esac +done + +# +# Move docker directories to content +# +for i in "${docker_dir[@]}" +do + : + if [ -d $i ] + then + mv $i /docs/content/ + fi +done + +rm -rf /docs/content/docker + diff --git a/docs/reference/create.md b/docs/reference/create.md index b6dd61c314..7313b94c09 100644 --- a/docs/reference/create.md +++ b/docs/reference/create.md @@ -4,6 +4,7 @@ title = "create" description = "Create a machine." keywords = ["machine, create, subcommand"] [menu.main] +identifier="machine.create" parent="smn_machine_subcmds" +++ @@ -74,8 +75,8 @@ As part of the process of creation, Docker Machine installs Docker and configures it with some sensible defaults. For instance, it allows connection from the outside world over TCP with TLS-based encryption and defaults to AUFS as the [storage -driver](https://docs.docker.com/reference/commandline/cli/#daemon-storage-driver-option) -when available. +driver](https://docs.docker.com/reference/commandline/daemon/#daemon-storage-driver-option) when +available. There are several cases where the user might want to set options for the created Docker engine (also known as the Docker _daemon_) themselves. For example, they diff --git a/docs/reference/inspect.md b/docs/reference/inspect.md index ecc144e4b2..f2fbe11d5f 100644 --- a/docs/reference/inspect.md +++ b/docs/reference/inspect.md @@ -4,6 +4,7 @@ title = "inspect" description = "Inspect information about a machine" keywords = ["machine, inspect, subcommand"] [menu.main] +identifier="machine.inspect" parent="smn_machine_subcmds" +++ diff --git a/docs/reference/kill.md b/docs/reference/kill.md index cda35d755e..74455a91ca 100644 --- a/docs/reference/kill.md +++ b/docs/reference/kill.md @@ -4,6 +4,7 @@ title = "kill" description = "Kill (abruptly force stop) a machine." keywords = ["machine, kill, subcommand"] [menu.main] +identifier="machine.kill" parent="smn_machine_subcmds" +++ diff --git a/docs/reference/restart.md b/docs/reference/restart.md index 227ed03c87..61050b8795 100644 --- a/docs/reference/restart.md +++ b/docs/reference/restart.md @@ -4,6 +4,7 @@ title = "restart" description = "Restart a machine" keywords = ["machine, restart, subcommand"] [menu.main] +identifier="machine.restart" parent="smn_machine_subcmds" +++ diff --git a/docs/reference/rm.md b/docs/reference/rm.md index 5e9e0c5768..c17418eace 100644 --- a/docs/reference/rm.md +++ b/docs/reference/rm.md @@ -4,6 +4,7 @@ title = "rm" description = "Remove a machine." keywords = ["machine, rm, subcommand"] [menu.main] +identifier="machine.rm" parent="smn_machine_subcmds" +++ diff --git a/docs/reference/start.md b/docs/reference/start.md index 366ded4dcc..d2f267dc0b 100644 --- a/docs/reference/start.md +++ b/docs/reference/start.md @@ -4,6 +4,7 @@ title = "start" description = "Start a machine" keywords = ["machine, start, subcommand"] [menu.main] +identifier="machine.start" parent="smn_machine_subcmds" +++ diff --git a/docs/reference/stop.md b/docs/reference/stop.md index b192a1f515..85651169a5 100644 --- a/docs/reference/stop.md +++ b/docs/reference/stop.md @@ -4,6 +4,7 @@ title = "stop" description = "Gracefully stop a machine" keywords = ["machine, stop, subcommand"] [menu.main] +identifier="machine.stop" parent="smn_machine_subcmds" +++