Allow rendering the spec as a website

The website isn't too pretty so far (especially when Javascript is
disabled), help welcome on that front. It should be usable though.

You can install mkdocs and the mkdocs-material theme from PyPI, then
run `mkdocs serve` to test changes locally.

Change-Id: Iaa33f936310f6e126f50e095e0b924babbdd8540

7 files changed, 99 insertions, 37 deletions

diff --git a/Makefile b/Makefile
deleted file mode 100644
index 3cfeb6f..0000000
--- a/Makefile
+++ /dev/null
@@ -1,7 +0,0 @@
-# Makefile for Baserock definitions format specification
-
-# This is available in the 'python3-markdown2' package on Fedora.
-MARKDOWN2 = markdown2-3.4
-
-spec.html: spec.mdwn
-	$(MARKDOWN2) $< > $@
diff --git a/README.mdwn b/README.mdwn
index c49202c..66702d5 100644
--- a/README.mdwn
+++ b/README.mdwn
@@ -13,6 +13,18 @@ The definitions format is documentated as a Markdown text file.
 
 See that text for more information about the Baserock definitions format.
 
+The contents of the 'master' branch is rendered as HTML at
+<http://docs.baserock.org/>. This is done using the 'mkdocs' static site
+generator.
+
+If you want to try out changes to the HTML rendering locally, install
+mkdocs and the required theme, then run `mkdocs serve` from the root
+directory of the repository. For example:
+
+    pip3.4 install --user mkdocs mkdocs-material
+    mkdocs serve
+    # Rendered content should now be visible at http://localhost:8000/
+
 
 JSON-Schemas
 ------------
diff --git a/changelog.mdwn b/changelog.mdwn
index 82dbb52..b88a131 100644
--- a/changelog.mdwn
+++ b/changelog.mdwn
@@ -1,12 +1,7 @@
-[[!meta title="Baserock definitions format, version history"]]
+Title: Baserock definitions format, version history
 
 This page describes the history of the Baserock definitions format.
 
-FIXME: A changelog should no longer be needed now that the spec is
-defined in a version control repository.
-
-See also: [[current]] version, and [[planned]] versions.
-
 # Version 7
 
 [Version 7](http://listmaster.pepperfish.net/pipermail/baserock-dev-baserock.org/2015-July/013220.html) adds a DEFAULTS file that specifies predefined build systems and predefined splitting rules. Previously it was up to the build tool to define these.
diff --git a/data/favicon.ico b/data/favicon.ico
new file mode 100644
index 0000000..bbc9bbd
--- /dev/null
+++ b/data/favicon.ico
diff --git a/index.mdwn b/index.mdwn
new file mode 100644
index 0000000..7f5dd63
--- /dev/null
+++ b/index.mdwn
@@ -0,0 +1,42 @@
+# Welcome to the Baserock Project's documentation!
+
+Baserock is about improving how we build, integrate and maintain collections of
+software.
+
+For more information, see these pages on the wiki:
+
+  - <http://wiki.baserock.org/overview/>
+  - <http://wiki.baserock.org/moving-parts/>
+
+## The Baserock definitions format
+
+The Baserock definitions format is a way of specifying components that
+need to be built, deployed and distributed in some way.
+
+The current format is described in the [Spec](spec) section.
+
+Historical changes are listed in the [Changelog](changelog).
+
+To propose changes to the version, please submit patches against 'master' of
+the [spec.git repo](http://git.baserock.org/cgit/baserock/baserock/spec.git).
+See the [contributing](http://wiki.baserock.org/contributing/) page for
+information. If you send a patch to Gerrit for a major change, please notify
+the baserock-dev@baserock.org mailing list too.
+
+The wiki has more [information on the Definitions
+format](http://wiki.baserock.org/definitions/), including a [comparison with
+other
+formats](http://wiki.baserock.org/definitions/comparison-with-other-formats),
+and a [style guide](http://wiki.baserock.org/definitions/best-practices).
+
+## The Baserock reference definitions
+
+We maintain a collection of definitions describing how to build lots of popular
+free software components. These are in a repository at
+[git.baserock.org/baserock/baserock/definitions](http://git.baserock.org/cgit/baserock/baserock/definitions.git/tree/).
+
+When modifying or defining your own Baserock systems, normally you will 'fork'
+this repository and use Git tooling to keep your changes in sync with ours.
+
+It's also possible to write definitions completely independently of ours, if
+you want.
diff --git a/mkdocs.yml b/mkdocs.yml
new file mode 100644
index 0000000..3c5b7e8
--- /dev/null
+++ b/mkdocs.yml
@@ -0,0 +1,28 @@
+# This file controls the HTML rendering of the contents of this repo.
+#
+# Rendering is done using the 'mkdocs' tool, available from
+# <http://www.mkdocs.org/>.
+
+
+site_name: Baserock Project documentation
+site_url: https://docs.baserock.org
+site_favicon: data/favicon.ico
+
+copyright: |
+  Unless otherwise noted, text in this repository is licensed under the
+  Creative Commons Attribution-ShareAlike 4.0 International license (CC BY-SA
+  4.0)
+
+pages:
+  - 'index.mdwn'
+  - 'Definitions format': 'spec.mdwn'
+  - 'changelog.mdwn'
+
+docs_dir: .
+
+site_dir: /srv/docs.baserock.org/
+
+# I chose this theme because it mostly functions without Javascript. Many
+# of the other mkdocs themes are pretty much unusable for users who have
+# Javascript turned off!
+theme: 'material'
diff --git a/spec.mdwn b/spec.mdwn
index 03fde9e..47fbfa0 100644
--- a/spec.mdwn
+++ b/spec.mdwn
@@ -1,4 +1,4 @@
-[[!meta title="Baserock definitions format"]]
+Title: Baserock definitions format
 
 The Baserock definitions format
 ===============================
@@ -6,29 +6,19 @@ The Baserock definitions format
 This page describes the Baserock definitions format (morph files). It is intended to be useful as
 an *informal* specification. It is not guaranteed to be accurate or exhaustive.
 
-If you are just getting started with Baserock, the [[quick-start]], [[devel-with]] and [[guides]] pages provide a more practical introduction.
+If you are just getting started with Baserock, the wiki pages [quick-start](http://wiki.baserock.org/quick-start), [devel-with](http://wiki.baserock.org/devel-with) and [guides](http://wiki.baserock.org/guides) pages provide a more practical introduction.
 
-The allowed YAML constructs are described in json-schema format here: <http://git.baserock.org/cgi-bin/cgit.cgi/baserock/baserock/definitions.git/tree/schemas>.
+The allowed YAML constructs are described in json-schema format here: <http://git.baserock.org/cgit/baserock/baserock/spec.git/tree/schemas>.
 
-The data model is described using OWL here: <http://git.baserock.org/cgi-bin/cgit.cgi/baserock/baserock/definitions.git/tree/schemas/baserock.owl>.
+The data model is described using OWL here: <http://git.baserock.org/cgit/baserock/baserock/spec.git/tree/schemas/baserock.owl>.
 
-The source code of [[Morph]] and [[YBD]] might be more useful if you need a completely accurate description of how the current Baserock definition format is used in practice.
-
-[[!toc startlevel=2 levels=2]]
+The source code of [Morph] and [YBD] might be more useful if you need a completely accurate description of how the current Baserock definition format is used in practice.
 
 Versioning
 ----------
 
 The current version of the definitions format is version 7.
 
-See also: the [[planned]] versions, and the [[historical]] versions of the
-format.
-
-Please propose changes to the format described here on the
-[[baserock-dev@baserock.org mailing list|mailinglist]]. Ideally, provide a
-patch for this file against the <git://baserock.branchable.com/> repo, but just
-describing the change you want to make is also fine.
-
 Definitions repository
 ----------------------
 
@@ -46,7 +36,7 @@ well, such as configuration data and documentation.
 The Baserock Project maintains a set of 'reference system definitions' at
 [git://git.baserock.org/baserock/baserock/definitions] (which can also be
 referred to as [baserock:baserock/definitions], when using the repo aliasing
-feature of [[Morph]]). That repo contains systems that can be built and
+feature of [Morph]). That repo contains systems that can be built and
 deployed as-is, but it is important that users can fork this repo as well,
 and work on systems in their version using `git merge` or `git rebase` to keep
 up to date with changes from upstream.
@@ -55,8 +45,8 @@ Baserock tooling should not mandate anything about the definitions repo that
 the user wants to process, other than the rules defined below.
 
 
-[git://git.baserock.org/baserock/baserock/definitions]: http://git.baserock.org/cgi-bin/cgit.cgi/baserock/baserock/definitions.git
-[baserock:baserock/definitions]: http://git.baserock.org/cgi-bin/cgit.cgi/baserock/baserock/definitions.git
+[git://git.baserock.org/baserock/baserock/definitions]: http://git.baserock.org/cgit/baserock/baserock/definitions.git
+[baserock:baserock/definitions]: http://git.baserock.org/cgit/baserock/baserock/definitions.git
 
 ### Structure
 
@@ -95,7 +85,7 @@ The toplevel entity in a definition is a dict, in all cases. Any syntax errors
 or type errors (such the toplevel entity being a number, or something) should
 be reported to the user.
 
-The [[Morph]] tool raises an error if any unknown dictionary keys are found in
+The [Morph] tool raises an error if any unknown dictionary keys are found in
 the definition, mainly so that it reports any spelling errors in key names.
 
 ### Common fields
@@ -276,10 +266,10 @@ Example system:
 ### Deployment definitions: Clusters
 
 **NOTE**: The deployment mechanism specified here is quite abstract. Most of
-the code used to do real-world deployments is currently tied to [[Morph]] and
+the code used to do real-world deployments is currently tied to [Morph] and
 kept in [morph.git].
 
-For 'deployment', [[Morph]] defines an API for running 'extensions'. The
+For 'deployment', [Morph] defines an API for running 'extensions'. The
 'cluster' and 'system' definitions together describe what extensions should be
 run, and what should be set in their environment, in order to deploy the
 system. See the "Deployment extension API" section below for how to find and
@@ -449,7 +439,7 @@ of the definitions.git repo. Configure extensions have the extension
 `.configure`, check extensions have the extension `.check`, and write
 extensions have the extension `.write`.
 
-[[Morph]] will look for extensions inside the 'morphlib' Python package, in the
+[Morph] will look for extensions inside the 'morphlib' Python package, in the
 `exts/` dir, before looking in the definitions.git repo.
 
 An extension must be executable using the [POSIX `exec()` system call]. We
@@ -457,7 +447,7 @@ encourage writing them as Python scripts and using a `#!/usr/bin/env python`
 [hashbang], but any executable code is permitted.
 
 The 'execution environment' for an extension is sadly unspecified at the moment.
-[[Morph]] runs extensions without any kid of chroot environment, but each one
+[Morph] runs extensions without any kid of chroot environment, but each one
 is run in a separate [mount namespace]. Running extensions chrooted into the
 system being deployed does not make sense, as it may not contain the right
 dependencies for the extensions to work, and it may expect to run on a
@@ -490,7 +480,7 @@ Extensions are expected to write status information to 'stdout', and any error
 messages to 'stderr'. This is for user feedback ONLY, deployment tools should
 not do anything with this data other than log and/or display it.
 
-[[Morph]] sets an extra environment variable `MORPH_LOG_FD` which is a file
+[Morph] sets an extra environment variable `MORPH_LOG_FD` which is a file
 descriptor that the extension can write log messages to, in order for them to
 appear in morph.log but not on stdout or stderr.
 
@@ -514,5 +504,7 @@ following content:
 
 Fill me in!
 
+[Morph]: http://wiki.baserock.org/Morph/
+[YBD]: http://wiki.baserock.org/ybd/
 [morph.git]: git://git.baserock.org/cgi-bin/cgit.cgi/baserock/baserock/morph
 [YAML]: http://yaml.org/