docs: Copy in API docs and add link

Make a copy of `apidoc/html` to `docs/reference` and then tell Jekyll to
include it verbatim. This will include the gtk-doc API docs on the
static site. A link is added to the main index.

A script is added to do the copy (a symlink won't do) and is setup to
run before Jekyll in the GitHub workflow. Ideally this would be a local
Jekyll plugin to make the process automatic, but the github-pages gem
doesn't allow that.

.github/workflows/docs.yml

@@ -51,6 +51,11 @@ jobs:
             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:
@@ -60,3 +65,5 @@ jobs:
           # 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

@@ -54,6 +54,7 @@ GITIGNOREFILES += \
 	docs/.bundle/ \
 	docs/Gemfile.lock \
 	docs/_site/ \
+	docs/reference/ \
 	docs/vendor/ \
 	$(NULL)
 

docs/README.md

@@ -22,7 +22,10 @@ bundle config set --local path vendor/bundle
 bundle install
 ```
 
-Finally, render and serve the site locally with Jekyll:
+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

@@ -13,8 +13,13 @@ 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,6 +141,10 @@ make
 make install DESTDIR=/path/to/dest
 ```
 
+## API Reference
+
+The libostree API documentation is available in [Reference](reference/).
+
 ## Contributing
 
 See [Contributing]({{ site.baseurl }}{% link CONTRIBUTING.md %}).

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"