Merge pull request #228 from cgwalters/docs-mkdocs

Docs mkdocs

Makefile.am

@@ -20,7 +20,7 @@ include Makefile-decls.am
 SUBDIRS += .
 
 if ENABLE_GTK_DOC
-SUBDIRS += doc
+SUBDIRS += api-doc
 endif
 
 ACLOCAL_AMFLAGS += -I m4 ${ACLOCAL_FLAGS}

README.md

@@ -1,20 +1,64 @@
-# rpm-ostree
-A system to compose RPMs on a server side into an
-[OSTree](https://wiki.gnome.org/Projects/OSTree)
-repository, and a client side tool to perform updates.
+# rpm-ostree Overview
+
+New! See the docs online at [Read The Docs (rpm-ostree)](https://rpm-ostree.readthedocs.org/en/latest/ )
+
+-----
+
+rpm-ostree is a hybrid image/package system.  It uses
+[OSTree](https://wiki.gnome.org/Projects/OSTree) as an image format,
+and uses RPM as a component model.
 
 The project aims to bring together a hybrid of image-like upgrade
 features (reliable replication, atomicity), with package-like
-flexibility (seeing package sets inside trees, layering, partial live
-updates).
+flexibility (introspecting trees to find package sets, package
+layering, partial live updates).
 
-## rpm-ostree is in beta!
-While many of the underlying technologies here are stable,
-if you are considering using this in your organization, you
-should perform a careful evaluation of the whole stack.  Software
-updates are obviously critical, and touch on many areas of concern.
+**Features:**
+
+ - Atomic upgrades and rollback for host system updates
+ - A server side tool to consume RPMs and commit them to an OSTree repository
+ - A system daemon to consume ostree commits as updates
+
+Projects using rpm-ostree
+-------------------------
+
+[Project Atomic](http://www.projectatomic.io/) uses rpm-ostree to
+provide a minimal host for Docker formatted Linux containers.
+Replicating a base immutable OS, then using Docker for applications.
+
+Building
+--------
+
+Releases are available as GPG signed git tags, and most recent
+versions support extended validation using
+[git-evtag](https://github.com/cgwalters/git-evtag).
+
+However, in order to build from a git clone, you must update the
+submodules.  If you're packaging and want a tarball, I recommend using
+a "recursive git archive" script.  There are several available online;
+[this code](https://git.gnome.org/browse/ostree/tree/packaging/Makefile.dist-packaging#n11)
+in OSTree is an example.
+
+Once you have a git clone or recursive archive, building is the
+same as almost every autotools project:
+
+```
+env NOCONFIGURE=1 ./autogen.sh
+./configure --prefix=...
+make
+make install DESTDIR=/path/to/dest
+```
+
+More documentation
+------------------
+
+New! See the docs online at [Read The Docs (OSTree)](https://ostree.readthedocs.org/en/latest/ )
+
+Some more information is available on the old wiki page:
+https://wiki.gnome.org/Projects/OSTree
+
+Contributing
+------------
+
+See [Contributing](CONTRIBUTING.md).
 
-### Contents
-* [Background and rationale](doc/background.md)
-* [Setting up and managing a compose server](doc/compose-server.md)
-* [Administering an rpm-ostree system](doc/administrator-handbook.md)

configure.ac

@@ -107,7 +107,7 @@ if test x$enable_compose_tooling != xno; then RPM_OSTREE_FEATURES="$RPM_OSTREE_F
 
 AC_CONFIG_FILES([
 Makefile
-doc/Makefile
+api-doc/Makefile
 src/lib/rpm-ostree-1.pc
 ])
 AC_OUTPUT

docs/CONTRIBUTING.md

@@ -0,0 +1,17 @@
+Submitting patches
+------------------
+
+Submit a pull request against <https://github.com/projectatomic/rpm-ostree>.
+
+Please look at "git log" and match the commit log style.
+
+Running the test suite
+----------------------
+
+Use `make check` for now.
+
+Coding style
+------------
+
+See the [OSTree CONTRIBUTING](https://git.gnome.org/browse/ostree/tree/docs/CONTRIBUTING.md)
+coding style.

docs/index.md

@@ -0,0 +1 @@
+../README.md

docs/manual/treefile.md

@@ -1,6 +1,15 @@
 Treefile
 --------
 
+A "treefile" is a made up term for a JSON-formatted specification used
+as input to `rpm-ostree compose tree` to bind "set of RPMs with
+configuration" to "OSTree commit".
+
+It's recommended to keep them in git, and set up a CI system like
+Jenkins to operate on them as it changes.
+
+It supports the following parameters:
+
  * `ref`: string, mandatory: Holds a string which will be the name of
    the branch for the content.
 

mkdocs.yml

@@ -0,0 +1,9 @@
+site_name: rpm-ostree
+pages:
+  - Home: 'index.md'
+  - Contributing: 'CONTRIBUTING.md'
+  - Manual:
+      - Background: 'manual/background.md'
+      - Client Administration: 'manual/administrator-handbook.md'
+      - Compose Server: 'manual/compose-server.md'
+      - Treefile: 'manual/treefile.md'