Merge pull request #2363 from dbnicholson/publish-api-docs

Publish libostree API docs

.github/workflows/docs.yml

@@ -0,0 +1,69 @@
+---
+name: Docs
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  docs:
+    name: Build documentation
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v2
+
+      # This is taken from ci/travis-install.sh but should probably be
+      # refactored.
+      - name: Install dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y \
+            attr \
+            bison \
+            cpio \
+            debhelper \
+            dh-autoreconf \
+            dh-systemd \
+            docbook-xml \
+            docbook-xsl \
+            e2fslibs-dev \
+            elfutils \
+            fuse \
+            gjs \
+            gnome-desktop-testing \
+            gobject-introspection \
+            gtk-doc-tools \
+            libarchive-dev \
+            libattr1-dev \
+            libcap-dev \
+            libfuse-dev \
+            libgirepository1.0-dev \
+            libglib2.0-dev \
+            libgpgme11-dev \
+            liblzma-dev \
+            libmount-dev \
+            libselinux1-dev \
+            libsoup2.4-dev \
+            libcurl4-openssl-dev \
+            procps \
+            zlib1g-dev \
+            python3-yaml
+
+      - name: Build API docs
+        run: |
+          ./autogen.sh --enable-gtk-doc
+          make -C apidoc
+
+      - name: Build and publish jekyll docs
+        uses: helaili/jekyll-action@v2
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          jekyll_src: docs
+          target_branch: gh-pages
+          # Only publish when pushing to main.
+          # XXX: Maybe this should only run on the release event?
+          build_only: ${{ github.ref == 'refs/heads/main' && 'false' || 'true' }}
+          # Run the prep script to put the API docs in place.
+          pre_build_commands: ./docs/prep-docs.sh

Makefile.am

@@ -49,6 +49,15 @@ GITIGNOREFILES += fastbuild-*.qcow2 _kola_temp/
 # Rust stuff
 GITIGNOREFILES += target/ Cargo.lock
 
+# Jekyll docs
+GITIGNOREFILES += \
+	docs/.bundle/ \
+	docs/Gemfile.lock \
+	docs/_site/ \
+	docs/reference/ \
+	docs/vendor/ \
+	$(NULL)
+
 SUBDIRS += .
 
 if ENABLE_GTK_DOC

docs/Gemfile

@@ -0,0 +1,14 @@
+# Bundler setup for jekyll to be deployed on github pages.
+
+source "https://rubygems.org"
+
+# Note that we're using the github-pages gem to mimic the GitHub pages
+# automated setup. That installs jekyll, a default set of jekyll
+# plugins, and a modified jekyll configuration.
+group :jekyll_plugins do
+  gem "github-pages"
+  gem "jekyll-remote-theme"
+end
+
+# Prefer the GitHub flavored markdown version of kramdown.
+gem "kramdown-parser-gfm"

docs/README.md

@@ -0,0 +1,31 @@
+This documentation is written in [Jekyll](https://jekyllrb.com/) format
+to be published on [GitHub Pages](https://pages.github.com/). The
+rendered HTML will be automatically built and published, but you can
+also use Jekyll locally to test changes.
+
+First you need to install [Ruby](https://www.ruby-lang.org/en/) and
+[RubyGems](https://rubygems.org/) to get Jekyll and the other gem
+dependencies. This is easiest using the distro's packages. On RedHat
+systems this is `rubygems` and on Debian systems this is
+`ruby-rubygems`.
+
+Next [Bundler](https://bundler.io/) is needed to install the gems using
+the provided [Gemfile](Gemfile). You can do this by running `gem install
+bundler` or using distro packages. On RedHat systems this is
+`rubygem-bundler` and on Debian systems this is `ruby-bundler`.
+
+Now you can prepare the Jekyll environment. Change to this directory and
+run:
+
+```
+bundle config set --local path vendor/bundle
+bundle install
+```
+
+Finally, run the `prep-docs.sh` script and then render and serve the
+site locally with Jekyll:
+
+```
+./prep-docs.sh
+bundle exec jekyll serve
+```

docs/_config.yml

@@ -7,6 +7,19 @@ url: "https://ostreedev.github.io"
 permalink: /:title/
 markdown: kramdown
 
+# Exclude the README and the bundler files that would normally be
+# ignored by default.
+exclude:
+  - README.md
+  - Gemfile
+  - Gemfile.lock
+  - prep-docs.sh
+  - vendor/
+
+# This is a copy of the apidoc/html directory. Run prep-docs.sh before
+# jekyll to put it in place.
+include: [reference]
+
 remote_theme: coreos/just-the-docs
 plugins:
   - jekyll-remote-theme

docs/index.md

@@ -141,9 +141,13 @@ make
 make install DESTDIR=/path/to/dest
 ```
 
+## API Reference
+
+The libostree API documentation is available in [Reference](reference/).
+
 ## Contributing
 
-See [Contributing](docs/CONTRIBUTING.md).
+See [Contributing]({{ site.baseurl }}{% link CONTRIBUTING.md %}).
 
 ## Licensing
 

docs/prep-docs.sh

@@ -0,0 +1,23 @@
+#!/bin/sh
+
+# Prepare docs directory for running jekyll. This would be better as a
+# local Jekyll plugin, but those aren't allowed by the github-pages gem.
+
+set -e
+
+docsdir=$(dirname "$0")
+topdir="$docsdir/.."
+
+# Make sure the API docs have been generated and copy them to the
+# reference directory.
+apidocs="$topdir/apidoc/html"
+refdir="$docsdir/reference"
+if [ ! -d "$apidocs" ]; then
+    echo "error: API docs $apidocs have not been generated" >&2
+    echo "Rebuild with --enable-gtk-doc option" >&2
+    exit 1
+fi
+
+echo "Copying $apidocs to $refdir"
+rm -rf "$refdir"
+cp -r "$apidocs" "$refdir"