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

diff --git a/Makefile.am b/Makefile.am
index 2f3cb53f3339d42c66d81650ba2f931aacb0f559..25428ec16928aaebea5561e5987d9c1bb5c9fd9e 100644 (file)
--- 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 (file)
index 0000000..1ffd2a0
--- /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 (file)
index 0000000..7963b04
--- /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 836b22d8428c685b4d360cca2907d31d149793b5..abe17b88272ff37a9a63496b4749e5a46811f355 100644 (file)
--- 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