docs: added theme
This commit is contained in:
dgarcia360
33
.github/workflows/pages.yml
vendored
Normal file
33
.github/workflows/pages.yml
vendored
Normal file
@@ -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 }}
|
||||
2
.gitignore
vendored
2
.gitignore
vendored
@@ -25,3 +25,5 @@ tags
|
||||
testlog
|
||||
test/*/*.reject
|
||||
.vscode
|
||||
docs/_build
|
||||
docs/poetry.lock
|
||||
|
||||
1
docs/CONTRIBUTING.md
Symbolic link
1
docs/CONTRIBUTING.md
Symbolic link
@@ -0,0 +1 @@
|
||||
../CONTRIBUTING.md
|
||||
1
docs/HACKING.md
Symbolic link
1
docs/HACKING.md
Symbolic link
@@ -0,0 +1 @@
|
||||
../HACKING.md
|
||||
76
docs/Makefile
Normal file
76
docs/Makefile
Normal file
@@ -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."
|
||||
20
docs/_utils/deploy.sh
Executable file
20
docs/_utils/deploy.sh
Executable file
@@ -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 "action@scylladb.com"
|
||||
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
|
||||
13
docs/_utils/redirect.sh
Executable file
13
docs/_utils/redirect.sh
Executable file
@@ -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_
|
||||
6
docs/_utils/redirections.yaml
Normal file
6
docs/_utils/redirections.yaml
Normal file
@@ -0,0 +1,6 @@
|
||||
### a dictionary of redirections
|
||||
#old path: new path
|
||||
#
|
||||
|
||||
# removing redirection html script files
|
||||
# test: /
|
||||
11
docs/_utils/setup.sh
Executable file
11
docs/_utils/setup.sh
Executable file
@@ -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
|
||||
197
docs/conf.py
Normal file
197
docs/conf.py
Normal file
@@ -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']
|
||||
41
docs/contents.rst
Normal file
41
docs/contents.rst
Normal file
@@ -0,0 +1,41 @@
|
||||
.. toctree::
|
||||
:hidden:
|
||||
:maxdepth: 2
|
||||
|
||||
index
|
||||
alternator/alternator
|
||||
redis/redis
|
||||
api_v2
|
||||
backport
|
||||
building
|
||||
cdc
|
||||
coding-style
|
||||
compaction_controller
|
||||
cql-extensions
|
||||
debugging
|
||||
docker-hub
|
||||
hinted_handoff_design
|
||||
IDL
|
||||
in_memory_representation
|
||||
isolation
|
||||
logging
|
||||
lua-type-mapping
|
||||
maintainer
|
||||
metrics
|
||||
migrating-from-users-to-roles
|
||||
paged-queries
|
||||
protocol-extensions
|
||||
protocols
|
||||
repair_based_node_ops
|
||||
review-checklist
|
||||
row_cache
|
||||
row_level_repair
|
||||
secondary_index
|
||||
sstable-scylla-format
|
||||
sstables-directory-structure
|
||||
system_keyspace
|
||||
system_schema_keyspace
|
||||
testing
|
||||
tracing
|
||||
CONTRIBUTING
|
||||
HACKING
|
||||
1
docs/index.md
Symbolic link
1
docs/index.md
Symbolic link
@@ -0,0 +1 @@
|
||||
README.md
|
||||
24
docs/pyproject.toml
Normal file
24
docs/pyproject.toml
Normal file
@@ -0,0 +1,24 @@
|
||||
[tool.poetry]
|
||||
name = "scylla"
|
||||
description = "Scylla Documentation"
|
||||
version = "4.3.0"
|
||||
authors = ["ScyllaDB Contributors"]
|
||||
|
||||
[tool.poetry.dependencies]
|
||||
python = "^3.7"
|
||||
pyyaml = "5.3"
|
||||
pygments = "2.2.0"
|
||||
recommonmark = "0.5.0"
|
||||
sphinx-scylladb-theme = "~0.1.11"
|
||||
sphinx-sitemap = "2.1.0"
|
||||
sphinx-autobuild = "0.7.1"
|
||||
Sphinx = "2.4.4"
|
||||
sphinx-multiversion-scylla = "0.2.4"
|
||||
sphinx-markdown-tables = "0.0.15"
|
||||
|
||||
[tool.poetry.dev-dependencies]
|
||||
pytest = "5.2"
|
||||
|
||||
[build-system]
|
||||
requires = ["poetry>=0.12"]
|
||||
build-backend = "poetry.masonry.api"
|
||||
Reference in New Issue
Block a user