Merge branch 'update-readme' into 'master'

Update README

See merge request !46

.gitignore

 pages/*
+public/

.gitlab-ci.yml

 image: registry.gitlab.com/gitlab-org/gitlab-build-images:doc-gitlab-com
 variables:
-  SITE_PATH: "public/"
   PROGRESS: "1"
 pages:

README.md

-# Introduction
-[Doc-gitlab-com](https://gitlab.com/gitlab-com/doc-gitlab-com/) generates html pages for the [GitLab documentation website](https://docs.gitlab.com/). The documentation is generated from the markdown files in /doc directory of the GitLab repo's. The conversion from markdown into html is done with [Pandoc](http://johnmacfarlane.net/pandoc/).
-If you want to contribute with documentation, please add them to the corresponding project:
+## Introduction
+[Doc-gitlab-com](https://gitlab.com/gitlab-com/doc-gitlab-com/) generates HTML
+pages for the [GitLab documentation website](https://docs.gitlab.com/). The
+documentation is generated from the Markdown files in the `/doc` directory of
+the GitLab repos. The conversion from Markdown into HTML is done with
+[Pandoc](http://johnmacfarlane.net/pandoc/).
+If you want to contribute with documentation, please add them to the
+corresponding project:
 + [GitLab CE](https://gitlab.com/gitlab-org/gitlab-ce/)
 + [GitLab EE](https://gitlab.com/gitlab-org/gitlab-ee/)
-And follow the [contributing guidelines](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/CONTRIBUTING.md#merge-request-guidelines) and [documentation styleguides](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/development/doc_styleguide.md) of each project.
-# Testing
-Please replace sytse with your username.
-```bash
-ssh sytse@doc.gitlab.com
-sudo su
-cd /root/doc-gitlab-com && git pull && ./generate.rb no-clone && service nginx restart
-```
-or to also update the repo's
-```bash
-cd /root/doc-gitlab-com && git pull && ./generate.rb && service nginx restart
-```
-# Restrictions
-
-+ All files should be in a doc/something directory, not any deeper.
-+ Only png image files are supported.
-
-# Installation
-
-Login as **root** and execute the following commands:
-
-```bash
-apt-get update
-apt-get upgrade
-apt-get remove pandoc # Pandoc 1.9.1 doesn't support pipe tables.
-apt-get install haskell-platform
-cabal update
-cabal install pandoc --ghc-options="-O0"
-ln -s /root/.cabal/bin/pandoc /usr/bin/pandoc
-cd /root
-git clone https://gitlab.com/gitlab-com/doc-gitlab-com.git
-ln -s /root/doc-gitlab-com/nginx /etc/nginx/sites-available/doc-gitlab-com
-ln -s /etc/nginx/sites-available/doc-gitlab-com /etc/nginx/sites-enabled/doc-gitlab-com
-rm /etc/nginx/sites-enabled/default
-service nginx start
-crontab -e
-20 */2 * * * /root/doc-gitlab-com/generate.rb
+And follow the [contributing guidelines][contributing] and
+[documentation styleguide][doc-styleguide] of each project.
+## Requirements
+Only 2 requirements:
+- Ruby
+- Pandoc
+No version restrictions, although you'd probably be better off using the
+latest of both.
+## Generation
+
+To build the documentation website we use the `generate.rb` script which:
+
+1. Clones the respective repositories in `/tmp/gitlab/`.
+1. Uses pandoc to create HTML documents from Markdown using `template.html` as
+   a template.
+1. Copies the stylesheets and the index page.
+
+By default, the site is built in the `public/` directory inside the root
+directory of this project. You can override this using the `SITE_PATH`
+environment variable.
+
+No console output will be created by default during the build process. If you
+want to see progress indicators, set the `PROGRESS` environment variable:
 ```
-Do not forget to add the public ssh key of the server `ssh-keygen` as a deploy key to any non-public repositories in generate.rb.
+PROGRESS=1 ./generate.rb
+```
+
+## Restrictions
+
+- Only png image files are supported.
+
+## Deployment process
+
+We use [GitLab Pages][pages] to build and host this website. You can see
+`.gitlab-ci.yml` for more information.
+
+A [job] is used to trigger a new build whenever tests run and pass on master
+branch of CE.
+[contributing]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/CONTRIBUTING.md#merge-request-guidelines
+[doc-styleguide]: https://docs.gitlab.com/ce/development/doc_styleguide.html
+[job]: https://gitlab.com/gitlab-org/gitlab-ce/blob/2c00d00ec1c39dbea0e0e54265027b5476b78e3c/.gitlab-ci.yml#L308-318

generate.rb

 #!/usr/bin/ruby
 # Generates the html documentation from the markdown files in the GitLab repo.
-# Call with no-clone to skip the timeconsuming closing process.
-# By default, the site is built in /srv/doc-gitlab-com. This location can be
+# Call with no-clone to skip the time consuming cloning process.
+# By default, the site is built in ./public. This location can be
 # overridden with the SITE_PATH environment variable.
 #
 # By default, this script will not create console output. If you want to see
@@ -24,7 +24,7 @@ def main
     'omnibus' => 'https://gitlab.com/gitlab-org/omnibus-gitlab.git'
   }
   repo_path = File.expand_path('..', __FILE__)
-  site_path = ENV['SITE_PATH'] || '/srv/doc-gitlab-com'
+  site_path = ENV['SITE_PATH'] || './public'
   repos.each do |relative_path, clone_url|