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.

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index 966f983ea469c76396739b3a0b4564bfbb9c48fc..6ff16fe7e1c9a51502b8831153efbc6d58f0b49d 100644 (file)
--- a/.github/workflows/docs.yml
+++ b/.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

diff --git a/Makefile.am b/Makefile.am
index 25428ec16928aaebea5561e5987d9c1bb5c9fd9e..1b9449c992bb3ed4ed4b7f2582f801f81b535124 100644 (file)
--- a/Makefile.am
+++ b/Makefile.am
@@ -54,6 +54,7 @@ GITIGNOREFILES += \
        docs/.bundle/ \
        docs/Gemfile.lock \
        docs/_site/ \
+       docs/reference/ \
        docs/vendor/ \
        $(NULL)
 

diff --git a/docs/README.md b/docs/README.md
index 7963b04eb7fb99c3e9dd8baf4f62401a2d33bc84..f1f89ecb3942b8de8f2d4f372e53c928d2f5d76c 100644 (file)
--- a/docs/README.md
+++ b/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
 ```

diff --git a/docs/_config.yml b/docs/_config.yml
index abe17b88272ff37a9a63496b4749e5a46811f355..44135c82b95601cd5da5aa45386e40d01fd763f5 100644 (file)
--- a/docs/_config.yml
+++ b/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

diff --git a/docs/index.md b/docs/index.md
index b6cdc663fe50a7960cf4309bdafaa80da90b9ba5..5d925d6f745408c2cbee9a34518c8665cd8a2a98 100644 (file)
--- a/docs/index.md
+++ b/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 %}).

diff --git a/docs/prep-docs.sh b/docs/prep-docs.sh
new file mode 100755 (executable)
index 0000000..2ae15a7
--- /dev/null
+++ b/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"