docs: added theme

sarvex · Dec 3, 2020 · a340b46 · a340b46
1 parent ea9c058
commit a340b46
Show file tree

Hide file tree

Showing 13 changed files with 426 additions and 0 deletions.
diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml
@@ -0,0 +1,33 @@
+name: "CI Docs"
+
+on:
+  push:
+    branches:
+    - master
+    tags:       
+    - '**'
+jobs:
+  release:
+    name: Build
+    runs-on: ubuntu-latest
+    env:
+      LATEST_VERSION: master
+    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 }}
diff --git a/.gitignore b/.gitignore
@@ -25,3 +25,5 @@ tags
 testlog
 test/*/*.reject
 .vscode
+docs/_build
+docs/poetry.lock
diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
@@ -0,0 +1 @@
+../CONTRIBUTING.md
diff --git a/docs/HACKING.md b/docs/HACKING.md
@@ -0,0 +1 @@
+../HACKING.md
diff --git a/docs/Makefile b/docs/Makefile
@@ -0,0 +1,76 @@
+# You can set these variables from the command line.
+POETRY        := $(HOME)/.poetry/bin/poetry
+SPHINXBUILD   := $(POETRY) run sphinx-build
+SPHINXOPTS    :=
+PAPER         :=
+BUILDDIR      := _build
+SOURCEDIR     := .
+
+# 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
+
+GIT_BRANCH = $(shell git branch --show-current)
+
+.PHONY: multiversion
+multiversion: setup
+	@mkdir -p $(HOME)/.cache/pypoetry/virtualenvs
+	$(POETRY) run sphinx-multiversion -D smv_branch_whitelist=$(GIT_BRANCH) -D smv_outputdir_format=$(GIT_BRANCH:branch-%=%) $(SOURCEDIR) $(BUILDDIR)/dirhtml
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
diff --git a/docs/_utils/deploy.sh b/docs/_utils/deploy.sh
@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+
+# Copy contents
+mkdir gh-pages
+cp -r ./docs/_build/dirhtml/* gh-pages
+./docs/_utils/redirect.sh > gh-pages/index.html
+
+# Create gh-pages branch
+cd gh-pages
+touch .nojekyll
+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
diff --git a/docs/_utils/redirect.sh b/docs/_utils/redirect.sh
@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+
+cat <<- _EOF_
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Redirecting to Documentation</title>
+    <meta charset="utf-8">
+    <meta http-equiv="refresh" content="0; URL=./${LATEST_VERSION}/index.html">
+    <link rel="canonical" href="./${LATEST_VERSION}/index.html">
+  </head>
+</html>
+_EOF_
diff --git a/docs/_utils/redirections.yaml b/docs/_utils/redirections.yaml
@@ -0,0 +1,6 @@
+### a dictionary of redirections
+#old path: new path
+#
+
+# removing redirection html script files
+# test: /
diff --git a/docs/_utils/setup.sh b/docs/_utils/setup.sh
@@ -0,0 +1,11 @@
+#!/usr/bin/env 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/master/get-poetry.py | python3 - && source ${HOME}/.poetry/env
+poetry install
+poetry update
diff --git a/docs/conf.py b/docs/conf.py
@@ -0,0 +1,197 @@
+# -*- coding: utf-8 -*-
+import os
+import sys
+from datetime import date
+from sphinx.util import logging
+import recommonmark
+from recommonmark.transform import AutoStructify
+
+logger = logging.getLogger(__name__)
+sys.path.insert(0, os.path.abspath('..'))
+
+# -- General configuration ------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#
+needs_sphinx = '1.8'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'sphinx.ext.todo',
+    'sphinx.ext.mathjax',
+    'sphinx.ext.githubpages',
+    'sphinx.ext.extlinks',
+    'sphinx_scylladb_theme',
+    'sphinx_multiversion',
+    'recommonmark',
+    'sphinx_markdown_tables',
+]
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+source_suffix = ['.rst', '.md']
+autosectionlabel_prefix_document = True
+
+# The encoding of source files.
+#
+# source_encoding = 'utf-8-sig'
+
+# The master toctree document.
+master_doc = 'contents'
+
+# General information about the project.
+project = 'Scylla Documentation'
+copyright = str(date.today().year) + ', ScyllaDB. All rights reserved.'
+author = u'Scylla Project Contributors'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = u'4.3'
+# The full version, including alpha/beta/rc tags.
+release = u'4.3.0'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This patterns also effect to html_static_path and html_extra_path
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'lib', 'lib64','**/_common/*', 'README.md', '.git', '.github', '_utils', '_templates', 'rst_include']
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = True
+
+# Setup Sphinx
+def setup(sphinx):
+    sphinx.add_config_value('recommonmark_config', {
+        'enable_eval_rst': True,
+        'enable_auto_toc_tree': False,
+    }, True)
+    sphinx.add_transform(AutoStructify)
+
+# Inline substitutions
+rst_prolog = """
+.. |mon_version| replace:: 3.1
+""" 
+
+# -- Options for HTML output ----------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'sphinx_scylladb_theme'
+html_theme_path = ["../.."]
+html_style = ''
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#
+html_theme_options = {
+    'header_links': [
+    ('Scylla Developer Notes', 'https://scylladb.github.io/scylla'),
+    ('Scylla University', 'https://university.scylladb.com/'),
+    ('ScyllaDB Home', 'https://www.scylladb.com/')],
+    'github_issues_repository': 'scylladb/scylla',
+    'show_sidebar_index': True,
+}
+
+extlinks = {}
+
+# If not None, a 'Last updated on:' timestamp is inserted at every page
+# bottom, using the given strftime format.
+# The empty string is equivalent to '%b %d, %Y'.
+#
+html_last_updated_fmt = '%d %B %Y'
+
+# Custom sidebar templates, maps document names to template names.
+#
+html_sidebars = {'**': ['side-nav.html']}
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'ScyllaDocumentationdoc'
+
+# URL which points to the root of the HTML documentation. 
+html_baseurl = 'https://scylladb.github.io/scylla'
+
+# Dictionary of values to pass into the template engine’s context for all pages
+html_context = {'html_baseurl': html_baseurl}
+
+# -- Options for not found extension -------------------------------------------
+
+# Template used to render the 404.html generated by this extension.
+notfound_template =  '404.html'
+
+# Prefix added to all the URLs generated in the 404 page.
+notfound_urls_prefix = ''
+
+# -- Options for redirect extension ---------------------------------------
+
+# Read a YAML dictionary of redirections and generate an HTML file for each
+redirects_file = "_utils/redirections.yaml"
+
+# -- Options for multiversion extension ----------------------------------
+# Whitelist pattern for tags (set to None to ignore all tags)
+smv_tag_whitelist = r'^.*$'
+# Whitelist pattern for branches (set to None to ignore all branches)
+smv_branch_whitelist = r"^master$"
+# Whitelist pattern for remotes (set to None to use local branches only)
+smv_remote_whitelist = r"^origin$"
+# Pattern for released versions
+smv_released_pattern = r'^tags/.*$'
+# Format for versioned output directories inside the build directory
+smv_outputdir_format = '{ref.name}'
+
+# -- Options for LaTeX page output ---------------------------------------
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [
+    (master_doc, 'ScyllaDocumentation.tex', u'Scylla Documentation',
+     u'Scylla Project Contributors', 'manual'),
+]
+
+# -- Options for manual page output ---------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    (master_doc, 'scylladocumentation', u'Scylla Documentation',
+     [author], 1)
+]
+
+# -- Options for Texinfo output -------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+    (master_doc, 'ScyllaDocumentation', u'Scylla Documentation',
+     author, 'ScyllaDocumentation', 'One line description of project.',
+     'Miscellaneous'),
+]
+
+# -- Options for Epub output ----------------------------------------------
+
+# Bibliographic Dublin Core info.
+epub_title = project
+epub_author = author
+epub_publisher = author
+epub_copyright = copyright
+
+# A list of files that should not be packed into the epub file.
+epub_exclude_files = ['search.html']