From d06c5d694b889f1ba363b5caaa6aed8e3a62df4b Mon Sep 17 00:00:00 2001 From: Colin Walters Date: Wed, 9 Mar 2016 10:58:13 -0500 Subject: [PATCH 1/2] docs: Start using mkdocs Matching https://git.gnome.org/browse/ostree/commit/docs/CONTRIBUTING.md?id=64ebe2b82ac25f1933f39a5cf8a24a5e0096cf6f --- README.md | 74 +++++++++++++++---- docs/CONTRIBUTING.md | 17 +++++ docs/index.md | 1 + .../manual}/administrator-handbook.md | 0 {doc => docs/manual}/background.md | 0 {doc => docs/manual}/compose-server.md | 0 {doc => docs/manual}/treefile.md | 9 +++ mkdocs.yml | 9 +++ 8 files changed, 95 insertions(+), 15 deletions(-) create mode 100644 docs/CONTRIBUTING.md create mode 120000 docs/index.md rename {doc => docs/manual}/administrator-handbook.md (100%) rename {doc => docs/manual}/background.md (100%) rename {doc => docs/manual}/compose-server.md (100%) rename {doc => docs/manual}/treefile.md (96%) create mode 100644 mkdocs.yml diff --git a/README.md b/README.md index 0a11c602..cb0da3cd 100644 --- a/README.md +++ b/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) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md new file mode 100644 index 00000000..f55af955 --- /dev/null +++ b/docs/CONTRIBUTING.md @@ -0,0 +1,17 @@ +Submitting patches +------------------ + +Submit a pull request against . + +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. diff --git a/docs/index.md b/docs/index.md new file mode 120000 index 00000000..32d46ee8 --- /dev/null +++ b/docs/index.md @@ -0,0 +1 @@ +../README.md \ No newline at end of file diff --git a/doc/administrator-handbook.md b/docs/manual/administrator-handbook.md similarity index 100% rename from doc/administrator-handbook.md rename to docs/manual/administrator-handbook.md diff --git a/doc/background.md b/docs/manual/background.md similarity index 100% rename from doc/background.md rename to docs/manual/background.md diff --git a/doc/compose-server.md b/docs/manual/compose-server.md similarity index 100% rename from doc/compose-server.md rename to docs/manual/compose-server.md diff --git a/doc/treefile.md b/docs/manual/treefile.md similarity index 96% rename from doc/treefile.md rename to docs/manual/treefile.md index 559d17b3..59bb7844 100644 --- a/doc/treefile.md +++ b/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. diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 00000000..b85da331 --- /dev/null +++ b/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' From e66333393e5b0be67fc2242e7ed88adc746f5433 Mon Sep 17 00:00:00 2001 From: Colin Walters Date: Wed, 9 Mar 2016 11:20:06 -0500 Subject: [PATCH 2/2] Move gtk-doc into api-doc Since that's all it is now, we use mkdocs for the manual. --- Makefile.am | 2 +- {doc => api-doc}/Makefile.am | 0 {doc => api-doc}/overview.xml | 0 {doc => api-doc}/rpmostree-docs.xml.in | 0 {doc => api-doc}/rpmostree-sections.txt | 0 {doc => api-doc}/treefile-examples/fedora-rawhide-base.json | 0 {doc => api-doc}/treefile-examples/fedora-rawhide-docker.json | 0 {doc => api-doc}/treefile-examples/fedora-rawhide.repo | 0 configure.ac | 2 +- 9 files changed, 2 insertions(+), 2 deletions(-) rename {doc => api-doc}/Makefile.am (100%) rename {doc => api-doc}/overview.xml (100%) rename {doc => api-doc}/rpmostree-docs.xml.in (100%) rename {doc => api-doc}/rpmostree-sections.txt (100%) rename {doc => api-doc}/treefile-examples/fedora-rawhide-base.json (100%) rename {doc => api-doc}/treefile-examples/fedora-rawhide-docker.json (100%) rename {doc => api-doc}/treefile-examples/fedora-rawhide.repo (100%) diff --git a/Makefile.am b/Makefile.am index c0bad761..d7926c62 100644 --- a/Makefile.am +++ b/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} diff --git a/doc/Makefile.am b/api-doc/Makefile.am similarity index 100% rename from doc/Makefile.am rename to api-doc/Makefile.am diff --git a/doc/overview.xml b/api-doc/overview.xml similarity index 100% rename from doc/overview.xml rename to api-doc/overview.xml diff --git a/doc/rpmostree-docs.xml.in b/api-doc/rpmostree-docs.xml.in similarity index 100% rename from doc/rpmostree-docs.xml.in rename to api-doc/rpmostree-docs.xml.in diff --git a/doc/rpmostree-sections.txt b/api-doc/rpmostree-sections.txt similarity index 100% rename from doc/rpmostree-sections.txt rename to api-doc/rpmostree-sections.txt diff --git a/doc/treefile-examples/fedora-rawhide-base.json b/api-doc/treefile-examples/fedora-rawhide-base.json similarity index 100% rename from doc/treefile-examples/fedora-rawhide-base.json rename to api-doc/treefile-examples/fedora-rawhide-base.json diff --git a/doc/treefile-examples/fedora-rawhide-docker.json b/api-doc/treefile-examples/fedora-rawhide-docker.json similarity index 100% rename from doc/treefile-examples/fedora-rawhide-docker.json rename to api-doc/treefile-examples/fedora-rawhide-docker.json diff --git a/doc/treefile-examples/fedora-rawhide.repo b/api-doc/treefile-examples/fedora-rawhide.repo similarity index 100% rename from doc/treefile-examples/fedora-rawhide.repo rename to api-doc/treefile-examples/fedora-rawhide.repo diff --git a/configure.ac b/configure.ac index c9d2bc37..59243651 100644 --- a/configure.ac +++ b/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