Merge pull request #1545 from moxiegirl/test-tooling

Updated for new documentation tooling
2015-06-15 10:36:37 -07:00 · 2015-06-15 10:36:37 -07:00 · aaccd12d3d
parent 5231288b4e e40fc02561
commit aaccd12d3d
15 changed files with 283 additions and 89 deletions
--- a/docs/Dockerfile
+++ b/docs/Dockerfile
@ -1,15 +1,24 @@
-FROM docs/base:latest
-MAINTAINER Sven Dowideit <SvenDowideit@docker.com> (@SvenDowideit)
+FROM docs/base:hugo
+MAINTAINER Mary Anthony <mary@docker.com> (@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 '/^<!.*metadata]>/g' \
+    -e '/^<!.*end-metadata.*>/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' {} \;
--- a/docs/Makefile
+++ 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)" .
--- a/docs/README.md
+++ 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.
+
+    <!--[metadata]>
+    +++
+    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
+    +++
+    <![end-metadata]-->  
+
+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.
--- 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
+<!--[metadata]>
+++
+title = "Compose CLI reference"
+description = "Compose CLI reference"
+keywords = ["fig, composition, compose, docker, orchestration, cli,  reference"]
+[menu.main]
+identifier = "smn_install_compose"
+parent = "smn_compose_ref"	
+++
+<![end-metadata]-->


-# 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)
--- a/docs/completion.md
+++ b/docs/completion.md
@ -1,7 +1,13 @@
---
-layout: default
-title: Command Completion
---
+<!--[metadata]>
+++
+title = "Command Completion"
+description = "Compose CLI reference"
+keywords = ["fig, composition, compose, docker, orchestration, cli,  reference"]
+[menu.main]
+parent="smn_workw_compose"
+weight=3
+++
+<![end-metadata]-->

 # Command Completion

@ -53,7 +59,7 @@ 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)
--- a/docs/compose-overview.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
+<!--[metadata]>
+++
+title = "Overview of Docker Compose"
+description = "Introduction and Overview of Compose"
+keywords = ["documentation, docs,  docker, compose, orchestration,  containers"]
+[menu.main]
+parent="smn_workw_compose"
+++
+<![end-metadata]-->


-# 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
--- 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
+<!--[metadata]>
+++
+title = "Quickstart Guide: Compose and Django"
+description = "Getting started with Docker Compose and Django"
+keywords = ["documentation, docs,  docker, compose, orchestration, containers"]
+[menu.main]
+parent="smn_workw_compose"
+weight=4
+++
+<![end-metadata]-->


-## 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)
--- a/docs/env.md
+++ b/docs/env.md
@ -1,9 +1,15 @@
---
-layout: default
-title: Compose environment variables reference
---
+<!--[metadata]>
+++
+title = "Compose environment variables reference"
+description = "Compose CLI reference"
+keywords = ["fig, composition, compose, docker, orchestration, cli,  reference"]
+[menu.main]
+parent="smn_compose_ref"
+weight=3
+++
+<![end-metadata]-->

-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)
--- 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
+<!--[metadata]>
+++
+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
+++
+<![end-metadata]-->


 ## 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)
--- 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
+<!--[metadata]>
+++
+title = "Docker Compose"
+description = "How to install Docker Compose"
+keywords = ["compose, orchestration, install, installation, docker, documentation"]
+[menu.main]
+parent="mn_install"
+weight=4
+++
+<![end-metadata]-->


-## 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)
--- a/docs/mkdocs.yml
+++ b/docs/mkdocs.yml
@ -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']
--- 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
+<!--[metadata]>
+++
+title = "Using Compose in production"
+description = "Guide to using Docker Compose in production"
+keywords = ["documentation, docs,  docker, compose, orchestration, containers,  production"]
+[menu.main]
+parent="smn_workw_compose"
+weight=1
+++
+<![end-metadata]-->


 ## Using Compose in production
--- 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
+<!--[metadata]>
+++
+title = "Quickstart Guide: Compose and Rails"
+description = "Getting started with Docker Compose and Rails"
+keywords = ["documentation, docs,  docker, compose, orchestration, containers"]
+[menu.main]
+parent="smn_workw_compose"
+weight=5
+++
+<![end-metadata]-->

-
-## 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)
--- 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
+<!--[metadata]>
+++
+title = "Quickstart Guide: Compose and Wordpress"
+description = "Getting started with Compose and Wordpress"
+keywords = ["documentation, docs,  docker, compose, orchestration, containers"]
+[menu.main]
+parent="smn_workw_compose"
+weight=6
+++
+<![end-metadata]-->

-## 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)
--- 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
---
+<!--[metadata]>
+++
+title = "docker-compose.yml reference"
+description = "docker-compose.yml reference"
+keywords = ["fig, composition, compose,  docker"]
+[menu.main]
+parent="smn_compose_ref"
+++
+<![end-metadata]-->
+

 # 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)