docs: add sphinx theme

Fixes #215

.github/workflows/book.yml

@@ -27,6 +27,6 @@ jobs:
     - name: Build the project
       run: cargo build --verbose --examples
     - name: Build the book
-      run: mdbook build book
+      run: mdbook build docs
     - name: Run book tests
-      run: SCYLLA_URI=scylladb:9042 mdbook test -L target/debug/deps book
+      run: SCYLLA_URI=scylladb:9042 mdbook test -L target/debug/deps docs

.github/workflows/pages.yml

@@ -0,0 +1,31 @@
+name: "CI Docs"
+
+on:
+  push:
+    branches:
+    - main
+    paths:
+    - 'docs/**'
+jobs:
+  release:
+    name: Build
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v2
+      with:
+        persist-credentials: false
+        fetch-depth: 0
+    - name: Set up Python
+      uses: actions/setup-python@v1
+      with:
+        python-version: 3.7
+    - name: Build docs
+      run: |
+        export PATH=$PATH:~/.local/bin
+        cd docs
+        make multiversion
+    - name: Deploy
+      run : ./docs/_utils/deploy.sh
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -3,3 +3,8 @@
 /target
 Cargo.lock
 /book/book
+/docs/_build
+/docs/book
+/docs/source/.doctrees
+/docs/poetry.lock
+.idea

docs/Makefile

@@ -0,0 +1,78 @@
+# You can set these variables from the command line.
+POETRY        = $(HOME)/.poetry/bin/poetry
+SPHINXOPTS    =
+SPHINXBUILD   = $(POETRY) run sphinx-build
+PAPER         =
+BUILDDIR      = _build
+SOURCEDIR     = source
+
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SOURCEDIR)
+# the i18n builder cannot share the environment and doctrees with the others
+I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SOURCEDIR)
+
+.PHONY: all
+all: dirhtml
+
+.PHONY: pristine
+pristine: clean
+	git clean -dfX
+
+.PHONY: setup
+setup:
+	./_utils/setup.sh
+
+.PHONY: clean
+clean:
+	rm -rf $(BUILDDIR)/*
+
+.PHONY: preview
+preview: setup
+	$(POETRY) run sphinx-autobuild -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml --port 5500
+
+.PHONY: dirhtml
+dirhtml: setup
+	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+.PHONY: singlehtml
+singlehtml: setup
+	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+	@echo
+	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+
+.PHONY: epub
+epub: 	setup
+	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+	@echo
+	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+
+.PHONY: epub3
+epub3:	setup
+	$(SPHINXBUILD) -b epub3 $(ALLSPHINXOPTS) $(BUILDDIR)/epub3
+	@echo
+	@echo "Build finished. The epub3 file is in $(BUILDDIR)/epub3."
+
+.PHONY: dummy
+dummy: 	setup
+	$(SPHINXBUILD) -b dummy $(ALLSPHINXOPTS) $(BUILDDIR)/dummy
+	@echo
+	@echo "Build finished. Dummy builder generates no files."
+
+.PHONY: linkcheck
+linkcheck: setup
+	$(SPHINXBUILD) -b linkcheck $(SOURCEDIR) $(BUILDDIR)/linkcheck
+
+.PHONY: multiversion
+multiversion: setup
+	@mkdir -p $(HOME)/.cache/pypoetry/virtualenvs
+	$(POETRY) run sphinx-multiversion source _build/dirhtml
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+.PHONY: multiversionpreview
+multiversionpreview: multiversion
+	$(POETRY) run python3 -m http.server 5500 --directory $(BUILDDIR)/dirhtml

docs/_utils/deploy.sh

@@ -0,0 +1,18 @@
+#!/bin/bash
+
+# Copy contents
+mkdir gh-pages
+cp -r ./docs/_build/dirhtml/. gh-pages
+
+# Create gh-pages branch
+cd gh-pages
+git init
+git config --local user.email "[email protected]"
+git config --local user.name "GitHub Action"
+git remote add origin "https://x-access-token:${GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}.git"
+git checkout -b gh-pages
+
+# Deploy
+git add .
+git commit -m "Publish docs" || true
+git push origin gh-pages --force

docs/_utils/pyproject_template.toml

@@ -0,0 +1,23 @@
+[tool.poetry]
+name = "sphinx-docs"
+description = "ScyllaDB Documentation"
+version = "0.1.0"
+authors = ["ScyllaDB Documentation Contributors"]
+
+[tool.poetry.dependencies]
+python = "^3.7"
+pyyaml = "5.3"
+pygments = "2.2.0"
+recommonmark = "0.5.0"
+sphinx-scylladb-theme = "~0.1.10"
+sphinx-sitemap = "2.1.0"
+sphinx-autobuild = "0.7.1"
+Sphinx = "2.4.4"
+sphinx-multiversion-scylla = "~0.2.6"
+
+[tool.poetry.dev-dependencies]
+pytest = "5.2"
+
+[build-system]
+requires = ["poetry>=0.12"]
+build-backend = "poetry.masonry.api" 

docs/_utils/redirections.yaml

@@ -0,0 +1,6 @@
+### a dictionary of redirections
+#old path: new path
+#
+
+# removing redirection html script files
+# test: /

docs/_utils/setup.sh

@@ -0,0 +1,12 @@
+#! /bin/bash
+
+if pwd | egrep -q '\s'; then
+	echo "Working directory name contains one or more spaces."
+	exit 1
+fi
+
+which python3 || { echo "Failed to find python3. Try installing Python for your operative system: https://www.python.org/downloads/" && exit 1; }
+which poetry || curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/1.1.3/get-poetry.py | python3 - && source ${HOME}/.poetry/env
+poetry install
+poetry update
+

book/book.toml → docs/book.toml

@@ -4,7 +4,7 @@ description = "Documentation for Scylla Rust Driver"
 authors = []
 language = "en"
 multilingual = false
-src = "src"
+src = "source"
 
 [rust]
 edition = "2018"