diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 00000000..6ff16fe7 --- /dev/null +++ b/.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 diff --git a/Makefile.am b/Makefile.am index 2f3cb53f..1b9449c9 100644 --- a/Makefile.am +++ b/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 diff --git a/docs/Gemfile b/docs/Gemfile new file mode 100644 index 00000000..1ffd2a02 --- /dev/null +++ b/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" diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..f1f89ecb --- /dev/null +++ b/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 +``` diff --git a/docs/_config.yml b/docs/_config.yml index 836b22d8..44135c82 100644 --- a/docs/_config.yml +++ b/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 diff --git a/docs/index.md b/docs/index.md index d5235ed6..5d925d6f 100644 --- a/docs/index.md +++ b/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 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"