diff --git a/docs/Dockerfile b/docs/Dockerfile index 59ef66cdd..55e7ce700 100644 --- a/docs/Dockerfile +++ b/docs/Dockerfile @@ -1,15 +1,24 @@ -FROM docs/base:latest -MAINTAINER Sven Dowideit (@SvenDowideit) +FROM docs/base:hugo +MAINTAINER Mary Anthony (@moxiegirl) -# to get the git info for this repo +# To get the git info for this repo COPY . /src -# Reset the /docs dir so we can replace the theme meta with the new repo's git info -RUN git reset --hard +COPY . /docs/content/compose/ -RUN grep "__version" /src/compose/__init__.py | sed "s/.*'\(.*\)'/\1/" > /docs/VERSION -COPY docs/* /docs/sources/compose/ -COPY docs/mkdocs.yml /docs/mkdocs-compose.yml - -# Then build everything together, ready for mkdocs -RUN /docs/build.sh +# 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) +# +# +RUN find /docs/content/compose -type f -name "*.md" -exec sed -i.old \ + -e '/^/g' \ + -e '/^/g' \ + -e 's/\([(]\)\(.*\)\(\.md\)/\1\2/g' \ + -e 's/\(\]\)\([(]\)\(\/\)/\1\2\/compose\//g' \ + -e 's/\(\][(]\)\([A-z]*[)]\)/\]\(\/compose\/\2/g' \ + -e 's/\(\][(]\)\(\.\.\/\)/\1\/compose\//g' {} \; diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 000000000..021e8f6e5 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,55 @@ +.PHONY: all binary build cross default docs docs-build docs-shell shell test test-unit test-integration test-integration-cli test-docker-py validate + +# env vars passed through directly to Docker's build scripts +# to allow things like `make DOCKER_CLIENTONLY=1 binary` easily +# `docs/sources/contributing/devenvironment.md ` and `project/PACKAGERS.md` have some limited documentation of some of these +DOCKER_ENVS := \ + -e BUILDFLAGS \ + -e DOCKER_CLIENTONLY \ + -e DOCKER_EXECDRIVER \ + -e DOCKER_GRAPHDRIVER \ + -e TESTDIRS \ + -e TESTFLAGS \ + -e TIMEOUT +# note: we _cannot_ add "-e DOCKER_BUILDTAGS" here because even if it's unset in the shell, that would shadow the "ENV DOCKER_BUILDTAGS" set in our Dockerfile, which is very important for our official builds + +# to allow `make DOCSDIR=docs docs-shell` (to create a bind mount in docs) +DOCS_MOUNT := $(if $(DOCSDIR),-v $(CURDIR)/$(DOCSDIR):/$(DOCSDIR)) + +# to allow `make DOCSPORT=9000 docs` +DOCSPORT := 8000 + +# Get the IP ADDRESS +DOCKER_IP=$(shell python -c "import urlparse ; print urlparse.urlparse('$(DOCKER_HOST)').hostname or ''") +HUGO_BASE_URL=$(shell test -z "$(DOCKER_IP)" && echo localhost || echo "$(DOCKER_IP)") +HUGO_BIND_IP=0.0.0.0 + +GIT_BRANCH := $(shell git rev-parse --abbrev-ref HEAD 2>/dev/null) +DOCKER_IMAGE := docker$(if $(GIT_BRANCH),:$(GIT_BRANCH)) +DOCKER_DOCS_IMAGE := docs-base$(if $(GIT_BRANCH),:$(GIT_BRANCH)) + + +DOCKER_RUN_DOCS := docker run --rm -it $(DOCS_MOUNT) -e AWS_S3_BUCKET -e NOCACHE + +# for some docs workarounds (see below in "docs-build" target) +GITCOMMIT := $(shell git rev-parse --short HEAD 2>/dev/null) + +default: docs + +docs: docs-build + $(DOCKER_RUN_DOCS) -p $(if $(DOCSPORT),$(DOCSPORT):)8000 -e DOCKERHOST "$(DOCKER_DOCS_IMAGE)" hugo server --port=$(DOCSPORT) --baseUrl=$(HUGO_BASE_URL) --bind=$(HUGO_BIND_IP) + +docs-draft: docs-build + $(DOCKER_RUN_DOCS) -p $(if $(DOCSPORT),$(DOCSPORT):)8000 -e DOCKERHOST "$(DOCKER_DOCS_IMAGE)" hugo server --buildDrafts="true" --port=$(DOCSPORT) --baseUrl=$(HUGO_BASE_URL) --bind=$(HUGO_BIND_IP) + + +docs-shell: docs-build + $(DOCKER_RUN_DOCS) -p $(if $(DOCSPORT),$(DOCSPORT):)8000 "$(DOCKER_DOCS_IMAGE)" bash + + +docs-build: +# ( git remote | grep -v upstream ) || git diff --name-status upstream/release..upstream/docs ./ > ./changed-files +# echo "$(GIT_BRANCH)" > GIT_BRANCH +# echo "$(AWS_S3_BUCKET)" > AWS_S3_BUCKET +# echo "$(GITCOMMIT)" > GITCOMMIT + docker build -t "$(DOCKER_DOCS_IMAGE)" . diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 000000000..00736e476 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,77 @@ +# Contributing to the Docker Compose documentation + +The documentation in this directory is part of the [https://docs.docker.com](https://docs.docker.com) website. 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. + +## Documentation contributing workflow + +1. Edit a Markdown file in the tree. + +2. Save your changes. + +3. Make sure you in your `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 appears 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/cli.md b/docs/cli.md index 1fbd4cb28..a2167d9c3 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -1,9 +1,16 @@ -page_title: Compose CLI reference -page_description: Compose CLI reference -page_keywords: fig, composition, compose, docker, orchestration, cli, reference + -# CLI reference +# Compose CLI reference Most Docker Compose commands are run against one or more services. If the service is not specified, the command will apply to all services. @@ -185,7 +192,7 @@ Configures the path to the `ca.pem`, `cert.pem`, and `key.pem` files used for TL ## Compose documentation -- [User guide](index.md) +- [User guide](compose-overview.md) - [Installing Compose](install.md) - [Get started with Django](django.md) - [Get started with Rails](rails.md) diff --git a/docs/completion.md b/docs/completion.md index 5168971f8..7fb696d80 100644 --- a/docs/completion.md +++ b/docs/completion.md @@ -1,7 +1,13 @@ ---- -layout: default -title: Command Completion ---- + # Command Completion @@ -53,11 +59,11 @@ Enjoy working with Compose faster and with less typos! ## Compose documentation -- [User guide](index.md) +- [User guide](compose-overview.md) - [Installing Compose](install.md) - [Get started with Django](django.md) - [Get started with Rails](rails.md) - [Get started with Wordpress](wordpress.md) - [Command line reference](cli.md) - [Yaml file reference](yml.md) -- [Compose environment variables](env.md) +- [Compose environment variables](env.md) \ No newline at end of file diff --git a/docs/index.md b/docs/compose-overview.md similarity index 96% rename from docs/index.md rename to docs/compose-overview.md index 981a02702..33629957a 100644 --- a/docs/index.md +++ b/docs/compose-overview.md @@ -1,11 +1,15 @@ -page_title: Compose: Multi-container orchestration for Docker -page_description: Introduction and Overview of Compose -page_keywords: documentation, docs, docker, compose, orchestration, containers + -# Docker Compose - -## Overview +# Overview of Docker Compose Compose is a tool for defining and running multi-container applications with Docker. With Compose, you define a multi-container application in a single diff --git a/docs/django.md b/docs/django.md index 4cbebe041..c44329e1c 100644 --- a/docs/django.md +++ b/docs/django.md @@ -1,10 +1,16 @@ -page_title: Quickstart Guide: Compose and Django -page_description: Getting started with Docker Compose and Django -page_keywords: documentation, docs, docker, compose, orchestration, containers, -django + -## Getting started with Compose and Django +## Quickstart Guide: Compose and Django This Quick-start Guide will demonstrate how to use Compose to set up and run a @@ -119,7 +125,7 @@ example, run `docker-compose up` and in another terminal run: ## More Compose documentation -- [User guide](index.md) +- [User guide](compose-overview.md) - [Installing Compose](install.md) - [Get started with Django](django.md) - [Get started with Rails](rails.md) diff --git a/docs/env.md b/docs/env.md index a4b543ae3..73496f32f 100644 --- a/docs/env.md +++ b/docs/env.md @@ -1,9 +1,15 @@ ---- -layout: default -title: Compose environment variables reference ---- + -Environment variables reference +# Compose environment variables reference =============================== **Note:** Environment variables are no longer the recommended method for connecting to linked services. Instead, you should use the link name (by default, the name of the linked service) as the hostname to connect to. See the [docker-compose.yml documentation](yml.md#links) for details. @@ -34,7 +40,7 @@ Fully qualified container name, e.g. `DB_1_NAME=/myapp_web_1/myapp_db_1` ## Compose documentation -- [User guide](index.md) +- [User guide](compose-overview.md) - [Installing Compose](install.md) - [Get started with Django](django.md) - [Get started with Rails](rails.md) diff --git a/docs/extends.md b/docs/extends.md index fd372ce2d..8527c81b3 100644 --- a/docs/extends.md +++ b/docs/extends.md @@ -1,6 +1,13 @@ -page_title: Extending services in Compose -page_description: How to use Docker Compose's "extends" keyword to share configuration between files and projects -page_keywords: fig, composition, compose, docker, orchestration, documentation, docs + ## Extending services in Compose @@ -79,7 +86,7 @@ For full details on how to use `extends`, refer to the [reference](#reference). ### Example use case In this example, you’ll repurpose the example app from the [quick start -guide](index.md). (If you're not familiar with Compose, it's recommended that +guide](compose-overview.md). (If you're not familiar with Compose, it's recommended that you go through the quick start first.) This example assumes you want to use Compose both to develop an application locally and then deploy it to a production environment. @@ -364,7 +371,7 @@ volumes: ## Compose documentation -- [User guide](index.md) +- [User guide](compose-overview.md) - [Installing Compose](install.md) - [Get started with Django](django.md) - [Get started with Rails](rails.md) diff --git a/docs/install.md b/docs/install.md index a521ec06c..ec0e6e4d5 100644 --- a/docs/install.md +++ b/docs/install.md @@ -1,14 +1,21 @@ -page_title: Installing Compose -page_description: How to install Docker Compose -page_keywords: compose, orchestration, install, installation, docker, documentation + -## Installing Compose +# Install Docker Compose To install Compose, you'll need to install Docker first. You'll then install Compose with a `curl` command. -### Install Docker +## Install Docker First, install Docker version 1.6 or greater: @@ -16,7 +23,7 @@ First, install Docker version 1.6 or greater: - [Instructions for Ubuntu](http://docs.docker.com/installation/ubuntulinux/) - [Instructions for other systems](http://docs.docker.com/installation/) -### Install Compose +## Install Compose To install Compose, run the following commands: @@ -38,7 +45,7 @@ You can test the installation by running `docker-compose --version`. ## Compose documentation -- [User guide](index.md) +- [User guide](compose-overview.md) - [Get started with Django](django.md) - [Get started with Rails](rails.md) - [Get started with Wordpress](wordpress.md) diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml deleted file mode 100644 index 428439bc4..000000000 --- a/docs/mkdocs.yml +++ /dev/null @@ -1,12 +0,0 @@ - -- ['compose/index.md', 'User Guide', 'Docker Compose' ] -- ['compose/production.md', 'User Guide', 'Using Compose in production' ] -- ['compose/extends.md', 'User Guide', 'Extending services in Compose'] -- ['compose/install.md', 'Installation', 'Docker Compose'] -- ['compose/cli.md', 'Reference', 'Compose command line'] -- ['compose/yml.md', 'Reference', 'Compose yml'] -- ['compose/env.md', 'Reference', 'Compose ENV variables'] -- ['compose/completion.md', 'Reference', 'Compose commandline completion'] -- ['compose/django.md', 'Examples', 'Getting started with Compose and Django'] -- ['compose/rails.md', 'Examples', 'Getting started with Compose and Rails'] -- ['compose/wordpress.md', 'Examples', 'Getting started with Compose and Wordpress'] diff --git a/docs/production.md b/docs/production.md index 60a6873da..294f3c4e8 100644 --- a/docs/production.md +++ b/docs/production.md @@ -1,6 +1,13 @@ -page_title: Using Compose in production -page_description: Guide to using Docker Compose in production -page_keywords: documentation, docs, docker, compose, orchestration, containers, production + ## Using Compose in production diff --git a/docs/rails.md b/docs/rails.md index aedb4c6e7..2ff6f1752 100644 --- a/docs/rails.md +++ b/docs/rails.md @@ -1,10 +1,15 @@ -page_title: Quickstart Guide: Compose and Rails -page_description: Getting started with Docker Compose and Rails -page_keywords: documentation, docs, docker, compose, orchestration, containers, -rails + - -## Getting started with Compose and Rails +## Quickstart Guide: Compose and Rails This Quickstart guide will show you how to use Compose to set up and run a Rails/PostgreSQL app. Before starting, you'll need to have [Compose installed](install.md). @@ -119,7 +124,7 @@ you're using Boot2docker, `boot2docker ip` will tell you its address). ## More Compose documentation -- [User guide](index.md) +- [User guide](compose-overview.md) - [Installing Compose](install.md) - [Get started with Django](django.md) - [Get started with Rails](rails.md) diff --git a/docs/wordpress.md b/docs/wordpress.md index b40d1a9f0..ad0e62966 100644 --- a/docs/wordpress.md +++ b/docs/wordpress.md @@ -1,14 +1,21 @@ -page_title: Quickstart Guide: Compose and Wordpress -page_description: Getting started with Docker Compose and Rails -page_keywords: documentation, docs, docker, compose, orchestration, containers, -wordpress + -## Getting started with Compose and Wordpress + +# Quickstart Guide: Compose and Wordpress You can use Compose to easily run Wordpress in an isolated environment built with Docker containers. -### Define the project +## Define the project First, [Install Compose](install.md) and then download Wordpress into the current directory: @@ -114,7 +121,7 @@ address). ## More Compose documentation -- [User guide](index.md) +- [User guide](compose-overview.md) - [Installing Compose](install.md) - [Get started with Django](django.md) - [Get started with Rails](rails.md) diff --git a/docs/yml.md b/docs/yml.md index df791bc98..80d6d719f 100644 --- a/docs/yml.md +++ b/docs/yml.md @@ -1,10 +1,13 @@ ---- -layout: default -title: docker-compose.yml reference -page_title: docker-compose.yml reference -page_description: docker-compose.yml reference -page_keywords: fig, composition, compose, docker ---- + + # docker-compose.yml reference @@ -390,7 +393,7 @@ read_only: true ## Compose documentation -- [User guide](index.md) +- [User guide](compose-overview.md) - [Installing Compose](install.md) - [Get started with Django](django.md) - [Get started with Rails](rails.md)