From 29457450049b50dca16b33d65ef6dfff2d92d27c Mon Sep 17 00:00:00 2001 From: Sam Thursfield Date: Mon, 29 Feb 2016 17:28:24 +0000 Subject: 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 --- Makefile | 7 ------- README.mdwn | 12 ++++++++++++ changelog.mdwn | 7 +------ data/favicon.ico | Bin 0 -> 709 bytes index.mdwn | 42 ++++++++++++++++++++++++++++++++++++++++++ mkdocs.yml | 28 ++++++++++++++++++++++++++++ spec.mdwn | 40 ++++++++++++++++------------------------ 7 files changed, 99 insertions(+), 37 deletions(-) delete mode 100644 Makefile create mode 100644 data/favicon.ico create mode 100644 index.mdwn create mode 100644 mkdocs.yml 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 +. 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 Binary files /dev/null and b/data/favicon.ico differ 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: + + - + - + +## 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 +# . + + +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: . +The allowed YAML constructs are described in json-schema format here: . -The data model is described using OWL here: . +The data model is described using OWL here: . -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 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/ -- cgit v1.2.1