diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 966f983e..6ff16fe7 100644 --- 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 25428ec1..1b9449c9 100644 --- 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 7963b04e..f1f89ecb 100644 --- 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 abe17b88..44135c82 100644 --- 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 b6cdc663..5d925d6f 100644 --- 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 index 00000000..2ae15a74 --- /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"