Merge pull request #2207 from travier/docs

docs: Add GitHub Pages support

README.md

@@ -1,9 +1,4 @@
-libostree
+# libostree
----------
-
-New! See the docs online at [Read The Docs (OSTree)](https://ostree.readthedocs.org/en/latest/ )
-
------
 
 This project is now known as "libostree", though it is still appropriate to use
 the previous name: "OSTree" (or "ostree"). The focus is on projects which use
@@ -36,8 +31,12 @@ version of
    projects like [flatpak](https://github.com/flatpak/flatpak) which
    use libostree for applications, rather than hosts.
 
-Operating systems and distributions using OSTree
+## Documentation
----------------------
+
+For more information, see the [project documentation](docs/index.md) or the
+[project documentation website](https://ostreedev.github.io/ostree).
+
+## Operating systems and distributions using OSTree
 
 [Endless OS](https://endlessos.com/) uses libostree for their host system as
 well as flatpak. See
@@ -63,8 +62,7 @@ system for GNOME.
 [Liri OS](https://liri.io/download/silverblue/) has the option to install
 their distribution using ostree.
 
-Distribution build tools
+## Distribution build tools
-------------------------
 
 [meta-updater](https://github.com/advancedtelematic/meta-updater) is
 a layer available for [OpenEmbedded](http://www.openembedded.org/wiki/Main_Page)
@@ -79,8 +77,7 @@ integration tool supports importing and exporting from libostree repos.
 Fedora [coreos-assembler](https://github.com/coreos/coreos-assembler) is
 the build tool used to generate Fedora CoreOS derivatives.
 
-Projects linking to libostree
+## Projects linking to libostree
------------------------------
 
 [rpm-ostree](https://github.com/projectatomic/rpm-ostree) is used by the
 Fedora-derived operating systems listed above.  It is a full hybrid
@@ -98,8 +95,7 @@ use the "libostree host system" aspects (e.g. bootloader management), just the
 "git-like hardlink dedup". For example, flatpak supports a per-user OSTree
 repository.
 
-Language bindings
+## Language bindings
-----
 
 libostree is accessible via [GObject Introspection](https://gi.readthedocs.io/en/latest/);
 any language which has implemented the GI binding model should work.
@@ -114,8 +110,7 @@ for statically compiled languages.  Here's a list of such bindings:
  - [ostree-go](https://github.com/ostreedev/ostree-go/)
  - [ostree-rs](https://gitlab.com/fkrull/ostree-rs/)
 
-Building
+## Building
---------
 
 Releases are available as GPG signed git tags, and most recent
 versions support extended validation using
@@ -139,19 +134,11 @@ make
 make install DESTDIR=/path/to/dest
 ```
 
-More documentation
+## Contributing
-------------------
-
-New! See the docs online at [Read The Docs (OSTree)](https://ostree.readthedocs.org/en/latest/ )
-
-Contributing
-------------
 
 See [Contributing](docs/CONTRIBUTING.md).
 
-
+## Licensing
-Licensing
--------
 
 The licensing for the *code* of libostree can be canonically found in the individual files;
 and the overall status in the [COPYING](https://github.com/ostreedev/ostree/blob/master/COPYING)

docs/CONTRIBUTING.md

@@ -1,5 +1,14 @@
-Submitting patches
+---
-------------------
+nav_order: 19
+---
+
+# Contributing
+{: .no_toc }
+
+1. TOC
+{:toc}
+
+## Submitting patches
 
 A majority of current maintainers prefer the GitHub pull request
 model, and this motivated moving the primary git repository to
@@ -26,8 +35,7 @@ Alternative methods if you don't like GitHub (also fully supported):
 It is likely however once a patch is ready to apply a maintainer
 will push it to a GitHub PR, and merge via Homu.
 
-Commit message style
+## Commit message style
---------------------
 
 Please look at `git log` and match the commit log style, which is very
 similar to the
@@ -66,15 +74,13 @@ For more information see [How to Write a Git Commit Message](https://chris.beams
 
 To edit the message from the most recent commit run `git commit --amend`. To change older commits on the branch use `git rebase -i`. For a successful rebase have the branch track `upstream master`. Once the changes have been made and saved, run `git push --force origin <branch-name>`.
 
-Running the test suite
+## Running the test suite
-----------------------
 
 OSTree uses both `make check` and supports the
 [Installed Tests](https://wiki.gnome.org/GnomeGoals/InstalledTests)
 model as well (if `--enable-installed-tests` is provided).
 
-Coding style
+## Coding style
-------------
 
 Indentation is GNU.  Files should start with the appropriate mode lines.
 
@@ -168,7 +174,6 @@ Instead do this:
           }
       }
 
-Contributing Tutorial
+## Contributing Tutorial
----------------------
 
 For a detailed walk-through on building, modifying, and testing, see this [tutorial on how to start contributing to OSTree](contributing-tutorial.md).

docs/README-historical.md

@@ -1,6 +1,11 @@
-This file is outdated, but some of the text here is still useful for
+---
+nav_order: 99
+title: Historical OSTree README
+---
+
+**This file is outdated, but some of the text here is still useful for
 historical context.  I'm preserving it (explicitly still in the tree)
-for posterity.
+for posterity.**
 
 OSTree
 ======
@@ -49,7 +54,7 @@ Comparison with existing tools
     Now your system is in an undefined state.  You can use e.g. rpm
     -qV to try to find out what you overwrote, but neither dpkg nor
     rpm will help clean up any files left over that aren't shipped by
-    the old package.  
+    the old package.
 
     This is most realistic option for people hacking on system
     components currently, but ostree will be better.
@@ -205,7 +210,7 @@ handling of binaries is very generic and unoptimized.
 
 In contrast, ostree is explicitly designed for binaries, and in
 particular one type of binary - ELF executables (or it will be once we
-start using bsdiff).  
+start using bsdiff).
 
 Another big difference versus git is that ostree uses hard links
 between "checkouts" and the repository.  This means each checkout uses

docs/_config.yml

@@ -0,0 +1,40 @@
+title: ostreedev/ostree
+description: ostree documentation
+baseurl: "/ostree"
+url: "https://coreos.github.io"
+# Comment above and use below for local development
+# url: "http://localhost:4000"
+permalink: /:title/
+markdown: kramdown
+
+remote_theme: coreos/just-the-docs
+plugins:
+  - jekyll-remote-theme
+
+color_scheme: coreos
+
+# Aux links for the upper right navigation
+aux_links:
+  "OSTree on GitHub":
+    - "https://github.com/ostreedev/ostree"
+
+footer_content: "Copyright &copy; <a href=\"https://www.redhat.com\">Red Hat, Inc.</a> and <a href=\"https://github.com/ostreedev\">others</a>."
+
+# Footer last edited timestamp
+last_edit_timestamp: true
+last_edit_time_format: "%b %e %Y at %I:%M %p"
+
+# Footer "Edit this page on GitHub" link text
+gh_edit_link: true
+gh_edit_link_text: "Edit this page on GitHub"
+gh_edit_repository: "https://github.com/ostreedev/ostree"
+gh_edit_branch: "master"
+gh_edit_view_mode: "tree"
+
+compress_html:
+  clippings: all
+  comments: all
+  endings: all
+  startings: []
+  blanklines: false
+  profile: false

docs/_sass/color_schemes/coreos.scss

@@ -0,0 +1 @@
+$link-color: #53a3da;

docs/adapting-existing.md

@@ -1,4 +1,12 @@
+---
+nav_order: 6
+---
+
 # Adapting existing mainstream distributions
+{: .no_toc }
+
+1. TOC
+{:toc}
 
 ## System layout
 

docs/atomic-upgrades.md

@@ -1,4 +1,12 @@
+---
+nav_order: 5
+---
+
 # Atomic Upgrades
+{: .no_toc }
+
+1. TOC
+{:toc}
 
 ## You can turn off the power anytime you want...
 

docs/buildsystem-and-repos.md

@@ -1,4 +1,12 @@
+---
+nav_order: 8
+---
+
 # Writing a buildsystem and managing repositories
+{: .no_toc }
+
+1. TOC
+{:toc}
 
 OSTree is not a package system.  It does not directly support building
 source code.  Rather, it is a tool for transporting and managing

docs/contributing-tutorial.md

@@ -1,21 +1,14 @@
+---
+nav_order: 20
+---
+
 # OSTree Contributing Tutorial
+{: .no_toc }
 
 The following guide is about OSTree forking, building, adding a command, testing the command, and submitting the change.
 
-- [Getting Started](#getting-started)
+1. TOC
-- [Building OSTree](#building-ostree)
+{:toc}
-    - [Install Build Dependencies](#install-build-dependencies)
-    - [OSTree Build Commands](#ostree-build-commands)
-- [Testing a Build](#testing-a-build)
-    - [Testing in a Container](#testing-in-a-container)
-    - [Testing in a Virtual Machine](#testing-in-a-virtual-machine)
-- [Tutorial: Adding a basic builtin command to OSTree](#tutorial-adding-a-basic-builtin-command-to-ostree)
-    - [Modifying OSTree](#modifying-ostree)
-    - [OSTree Tests](#ostree-tests)
-    - [Submitting a Patch](#submitting-a-patch)
-    - [Returning Workflow](#returning-workflow)
-
----
 
 ## Getting Started
 

docs/deployment.md

@@ -1,4 +1,12 @@
+---
+nav_order: 4
+---
+
 # Deployments
+{: .no_toc }
+
+1. TOC
+{:toc}
 
 ## Overview
 

docs/formats.md

@@ -1,4 +1,12 @@
+---
+nav_order: 7
+---
+
 # OSTree data formats
+{: .no_toc }
+
+1. TOC
+{:toc}
 
 ## On the topic of "smart servers"
 

docs/index.md

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

docs/index.md

@@ -0,0 +1,154 @@
+---
+nav_order: 1
+---
+
+# libostree
+{: .no_toc }
+
+1. TOC
+{:toc}
+
+This project is now known as "libostree", though it is still appropriate to use
+the previous name: "OSTree" (or "ostree"). The focus is on projects which use
+libostree's shared library, rather than users directly invoking the command line
+tools (except for build systems). However, in most of the rest of the
+documentation, we will use the term "OSTree", since it's slightly shorter, and
+changing all documentation at once is impractical. We expect to transition to
+the new name over time.
+
+As implied above, libostree is both a shared library and suite of command line
+tools that combines a "git-like" model for committing and downloading bootable
+filesystem trees, along with a layer for deploying them and managing the
+bootloader configuration.
+
+The core OSTree model is like git in that it checksums individual files and has
+a content-addressed-object store. It's unlike git in that it "checks out" the
+files via hardlinks, and they thus need to be immutable to prevent corruption.
+Therefore, another way to think of OSTree is that it's just a more polished
+version of
+[Linux VServer hardlinks](http://linux-vserver.org/index.php?title=util-vserver:Vhashify&oldid=2285).
+
+**Features:**
+
+ - Transactional upgrades and rollback for the system
+ - Replicating content incrementally over HTTP via GPG signatures and "pinned TLS" support
+ - Support for parallel installing more than just 2 bootable roots
+ - Binary history on the server side (and client)
+ - Introspectable shared library API for build and deployment systems
+ - Flexible support for multiple branches and repositories, supporting
+   projects like [flatpak](https://github.com/flatpak/flatpak) which
+   use libostree for applications, rather than hosts.
+
+## Operating systems and distributions using OSTree
+
+[Endless OS](https://endlessos.com/) uses libostree for their host system as
+well as flatpak. See
+their [eos-updater](https://github.com/endlessm/eos-updater)
+and [deb-ostree-builder](https://github.com/dbnicholson/deb-ostree-builder)
+projects.
+
+Fedora derivatives use rpm-ostree (noted below); there are 3 variants using OSTree:
+
+ - [Fedora CoreOS](https://getfedora.org/en/coreos/)
+ - [Fedora Silverblue](https://silverblue.fedoraproject.org/)
+ - [Fedora IoT](https://iot.fedoraproject.org/)
+
+Red Hat Enterprise Linux CoreOS is a derivative of Fedora CoreOS, used in [OpenShift 4](https://try.openshift.com/).
+The [machine-config-operator](https://github.com/openshift/machine-config-operator/blob/master/docs/OSUpgrades.md)
+manages upgrades.  RHEL CoreOS is also the successor to RHEL Atomic Host, which
+uses rpm-ostree as well.
+
+[GNOME Continuous](https://wiki.gnome.org/Projects/GnomeContinuous) is
+where OSTree was born - as a high performance continuous delivery/testing
+system for GNOME.
+
+[Liri OS](https://liri.io/download/silverblue/) has the option to install
+their distribution using ostree.
+
+## Distribution build tools
+
+[meta-updater](https://github.com/advancedtelematic/meta-updater) is
+a layer available for [OpenEmbedded](http://www.openembedded.org/wiki/Main_Page)
+systems.
+
+[QtOTA](http://doc.qt.io/QtOTA/) is Qt's over-the-air update framework
+which uses libostree.
+
+The [BuildStream](https://gitlab.com/BuildStream/buildstream) build and
+integration tool supports importing and exporting from libostree repos.
+
+Fedora [coreos-assembler](https://github.com/coreos/coreos-assembler) is
+the build tool used to generate Fedora CoreOS derivatives.
+
+## Projects linking to libostree
+
+[rpm-ostree](https://github.com/projectatomic/rpm-ostree) is used by the
+Fedora-derived operating systems listed above.  It is a full hybrid
+image/package system.  By default it uses libostree to atomically replicate a base OS
+(all dependency resolution is done on the server), but it supports "package layering", where
+additional RPMs can be layered on top of the base.  This brings a "best of both worlds""
+model for image and package systems.
+
+[eos-updater](https://github.com/endlessm/eos-updater) is a daemon that implements updates
+on EndlessOS.
+
+[flatpak](https://github.com/flatpak/flatpak) uses libostree for desktop
+application containers. Unlike most of the other systems here, flatpak does not
+use the "libostree host system" aspects (e.g. bootloader management), just the
+"git-like hardlink dedup". For example, flatpak supports a per-user OSTree
+repository.
+
+## Language bindings
+
+libostree is accessible via [GObject Introspection](https://gi.readthedocs.io/en/latest/);
+any language which has implemented the GI binding model should work.
+For example, Both [pygobject](https://pygobject.readthedocs.io/en/latest/)
+and [gjs](https://gitlab.gnome.org/GNOME/gjs) are known to work
+and further are actually used in libostree's test suite today.
+
+Some bindings take the approach of using GI as a lower level and
+write higher level manual bindings on top; this is more common
+for statically compiled languages.  Here's a list of such bindings:
+
+ - [ostree-go](https://github.com/ostreedev/ostree-go/)
+ - [ostree-rs](https://gitlab.com/fkrull/ostree-rs/)
+
+## 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 OSTree and want a tarball, I
+recommend using a "recursive git archive" script.  There are several
+available online;
+[this code](https://github.com/ostreedev/ostree/blob/master/packaging/Makefile.dist-packaging#L11)
+in OSTree is an example.
+
+Once you have a git clone or recursive archive, building is the
+same as almost every autotools project:
+
+```
+git submodule update --init
+env NOCONFIGURE=1 ./autogen.sh
+./configure --prefix=...
+make
+make install DESTDIR=/path/to/dest
+```
+
+## Contributing
+
+See [Contributing](docs/CONTRIBUTING.md).
+
+## Licensing
+
+The licensing for the *code* of libostree can be canonically found in the individual files;
+and the overall status in the [COPYING](https://github.com/ostreedev/ostree/blob/master/COPYING)
+file in the source.  Currently, that's LGPLv2+.  This also covers the man pages and API docs.
+
+The license for the manual documentation in the `doc/` directory is:
+`SPDX-License-Identifier: (CC-BY-SA-3.0 OR GFDL-1.3-or-later)`
+This is intended to allow use by Wikipedia and other projects.
+
+In general, files should have a `SPDX-License-Identifier` and that is canonical.

docs/introduction.md

@@ -1,4 +1,12 @@
+---
+nav_order: 2
+---
+
 # OSTree Overview
+{: .no_toc }
+
+1. TOC
+{:toc}
 
 ## Introduction
 

docs/related-projects.md

@@ -1,4 +1,12 @@
+---
+nav_order: 10
+---
+
 # Related Projects
+{: .no_toc }
+
+1. TOC
+{:toc}
 
 OSTree is in many ways very evolutionary.  It builds on concepts and
 ideas introduced from many different projects such as

docs/repo.md

@@ -1,4 +1,12 @@
+---
+nav_order: 3
+---
+
 # Anatomy of an OSTree repository
+{: .no_toc }
+
+1. TOC
+{:toc}
 
 ## Core object types and data model
 

docs/repository-management.md

@@ -1,4 +1,12 @@
+---
+nav_order: 9
+---
+
 # Managing content in OSTree repositories
+{: .no_toc }
+
+1. TOC
+{:toc}
 
 Once you have a build system going, if you actually want client
 systems to retrieve the content, you will quickly feel a need for