From e4105a0366bf0d905c610a18ad6e343ae9965b2e Mon Sep 17 00:00:00 2001 From: Dan Nicholson Date: Thu, 20 May 2021 16:42:29 -0600 Subject: [PATCH 1/4] docs: Fix CONTRIBUTING link This returns a 404 since the site is already generated from the docs directory. Furthermore, the `CONTRIBUTING.md` markdown file isn't in the generated site, just the HTML. Instead, use jekyll's `link` tag to create the link. Unfortunately, before jekyll 4.0 (github-pages uses 3.9), you have to prepend the base URL. --- docs/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.md b/docs/index.md index d5235ed6..b6cdc663 100644 --- a/docs/index.md +++ b/docs/index.md @@ -143,7 +143,7 @@ make install DESTDIR=/path/to/dest ## Contributing -See [Contributing](docs/CONTRIBUTING.md). +See [Contributing]({{ site.baseurl }}{% link CONTRIBUTING.md %}). ## Licensing From 3c7449397a6e49df4d717317945ff1274f020606 Mon Sep 17 00:00:00 2001 From: Dan Nicholson Date: Thu, 20 May 2021 14:48:16 -0600 Subject: [PATCH 2/4] docs: Provide bundler setup for building site locally This mimics the GitHub Pages environment so that you can build and serve the site locally for testing. It's will also be required later for using Jekyll Actions[1] instead of the automated GitHub Pages flow. 1. https://github.com/marketplace/actions/jekyll-actions --- Makefile.am | 8 ++++++++ docs/Gemfile | 14 ++++++++++++++ docs/README.md | 28 ++++++++++++++++++++++++++++ docs/_config.yml | 8 ++++++++ 4 files changed, 58 insertions(+) create mode 100644 docs/Gemfile create mode 100644 docs/README.md diff --git a/Makefile.am b/Makefile.am index 2f3cb53f..25428ec1 100644 --- a/Makefile.am +++ b/Makefile.am @@ -49,6 +49,14 @@ GITIGNOREFILES += fastbuild-*.qcow2 _kola_temp/ # Rust stuff GITIGNOREFILES += target/ Cargo.lock +# Jekyll docs +GITIGNOREFILES += \ + docs/.bundle/ \ + docs/Gemfile.lock \ + docs/_site/ \ + 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..7963b04e --- /dev/null +++ b/docs/README.md @@ -0,0 +1,28 @@ +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, render and serve the site locally with Jekyll: +``` +bundle exec jekyll serve +``` diff --git a/docs/_config.yml b/docs/_config.yml index 836b22d8..abe17b88 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -7,6 +7,14 @@ 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 + - vendor/ + remote_theme: coreos/just-the-docs plugins: - jekyll-remote-theme From 19a306ecefa6f1ef84e7e4c03cd533c30d070fbe Mon Sep 17 00:00:00 2001 From: Dan Nicholson Date: Thu, 20 May 2021 16:03:25 -0600 Subject: [PATCH 3/4] docs: Add github workflow for building and publishing docs This uses the Jekyll Actions GitHub action to push the rendered docs to the gh-pages branch rather than GitHub's automated docs flow. That will allow greater control over how the docs are generated. Pushing to the gh-pages branch only happens on pushes to main. For pull requests, the docs are only built. --- .github/workflows/docs.yml | 62 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 62 insertions(+) create mode 100644 .github/workflows/docs.yml diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 00000000..966f983e --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,62 @@ +--- +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 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' }} From e19840a25220b399fb213407ec545c8262d1bc39 Mon Sep 17 00:00:00 2001 From: Dan Nicholson Date: Thu, 20 May 2021 16:03:56 -0600 Subject: [PATCH 4/4] 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 | 7 +++++++ Makefile.am | 1 + docs/README.md | 5 ++++- docs/_config.yml | 5 +++++ docs/index.md | 4 ++++ docs/prep-docs.sh | 23 +++++++++++++++++++++++ 6 files changed, 44 insertions(+), 1 deletion(-) create mode 100755 docs/prep-docs.sh 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"