bahman/scylla
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

Review docs config

Browse Source
This commit is contained in:
David Garcia
2021-10-22 13:34:56 +01:00
parent 23886b2219
commit ff56b7e43e
4 changed files with 70 additions and 157 deletions
Download Patch File Download Diff File Expand all files Collapse all files

42
.github/workflows/docs-pages@v2.yaml vendored
View File

@@ -1,31 +1,29 @@
name: "Publish docs to GitHub Pages"
name: "Docs / Publish"
on:
push:
branches:
- master
- master
paths:
- "docs/**"
- "docs/**"
workflow_dispatch:
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 }}
- 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: make -C docs multiversion
- name: Deploy
run: ./docs/_utils/deploy.sh
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

33
.github/workflows/docs-pr@v1.yaml vendored
View File

@@ -1,28 +1,25 @@
name: "Build docs on pull requests"
name: "Docs / Build PR"
on:
pull_request:
branches:
- master
- master
paths:
- "docs/**"
- "docs/**"
jobs:
release:
build:
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 test
- 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: make -C docs test

4
docs/Makefile
View File

@@ -10,7 +10,7 @@ SOURCEDIR := .
PAPEROPT_a4 := -D latex_paper_size=a4
PAPEROPT_letter := -D latex_paper_size=letter
ALLSPHINXOPTS := -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SOURCEDIR)
TESTSPHINXOPTS = $(ALLSPHINXOPTS) -W --keep-going
TESTSPHINXOPTS := $(ALLSPHINXOPTS) -W --keep-going
# the i18n builder cannot share the environment and doctrees with the others
I18NSPHINXOPTS := $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SOURCEDIR)
@@ -83,4 +83,4 @@ multiversionpreview: multiversion
test: setup
$(SPHINXBUILD) -b dirhtml $(TESTSPHINXOPTS) $(BUILDDIR)/dirhtml
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."

148
docs/conf.py
View File

@@ -2,20 +2,14 @@
import os
import sys
from datetime import date
from sphinx.util import logging
import recommonmark
from recommonmark.transform import AutoStructify
from sphinx_scylladb_theme.utils import multiversion_regex_builder
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.
@@ -36,10 +30,6 @@ extensions = [
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'
@@ -48,26 +38,10 @@ 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']
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'README.md', '_utils']
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
@@ -83,60 +57,6 @@ def setup(sphinx):
}, True)
sphinx.add_transform(AutoStructify)
# Custom lexer
from pygments.lexers.shell import BashLexer
from sphinx.highlighting import lexers
class CqlLexer(BashLexer):
pass
lexers['cql'] = CqlLexer(startinline=True)
# 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 = {
'github_issues_repository': 'scylladb/scylla',
'hide_version_dropdown': ['master'],
'default_branch': 'stable',
'hide_sidebar_index': 'False',
}
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://scylla.docs.scylladb.com'
# 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.
@@ -168,44 +88,42 @@ smv_released_pattern = r'^tags/.*$'
# Format for versioned output directories inside the build directory
smv_outputdir_format = '{ref.name}'
# -- Options for HTML output ----------------------------------------------
# -- Options for LaTeX page 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'
# 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'),
]
# 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 = {
'conf_py_path': 'docs/',
'default_branch': 'master',
'github_repository': 'scylladb/scylla',
'github_issues_repository': 'scylladb/scylla',
'hide_edit_this_page_button': 'false',
'hide_sidebar_index': 'false',
'hide_version_dropdown': ['master'],
}
# -- Options for manual page output ---------------------------------------
# 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'
# 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)
]
# Custom sidebar templates, maps document names to template names.
#
html_sidebars = {'**': ['side-nav.html']}
# -- Options for Texinfo output -------------------------------------------
# Output file base name for HTML help builder.
htmlhelp_basename = 'ScyllaDocumentationdoc'
# 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'),
]
# URL which points to the root of the HTML documentation.
html_baseurl = 'https://scylla.docs.scylladb.com'
# -- 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']
# Dictionary of values to pass into the template engine’s context for all pages
html_context = {'html_baseurl': html_baseurl}