Add Scylla Sphinx Theme 1.0 (#50)

* Upgrade Sphinx theme to version 1.x

* Update docs/source/conf.py

Co-authored-by: David Garcia <[email protected]>

* Update .github/workflows/[email protected]

Co-authored-by: David Garcia <[email protected]>

* Update .github/workflows/[email protected]

Co-authored-by: David Garcia <[email protected]>

* Update .github/workflows/[email protected]

Co-authored-by: David Garcia <[email protected]>

* Update .github/workflows/[email protected]

Co-authored-by: David Garcia <[email protected]>

* Update .github/workflows/[email protected]

Co-authored-by: David Garcia <[email protected]>

* Update .github/workflows/[email protected]

Co-authored-by: David Garcia <[email protected]>

* Update docs build scripts

Co-authored-by: Laura Novich <[email protected]>
Co-authored-by: Laura Novich <[email protected]>

Author: dgarcia360

.github/workflows/pages.yml renamed to .github/workflows/[email protected]

@@ -1,15 +1,16 @@
-name: "CI Docs"
+name: "Docs / Publish"
 
 on:
   push:
     branches:
     - master
     paths:
-    - 'docs/**'
-    - 'topics/**'
+    - "docs/**"
+    - "topics/**"
+  workflow_dispatch:
+
 jobs:
   release:
-    name: Build
     runs-on: ubuntu-latest
     steps:
     - name: Checkout
@@ -21,14 +22,11 @@ jobs:
       uses: actions/setup-python@v1
       with:
         python-version: 3.7
-    - name: Set up Doxygen	    
-      run: sudo apt-get install doxygen	
+    - name: Set up Doxygen
+      run: sudo apt-get install doxygen
     - name: Build docs
-      run: |
-        export PATH=$PATH:~/.local/bin
-        cd docs
-        make multiversion
-    - name: Deploy
-      run : ./docs/_utils/deploy.sh
+      run: make -C docs multiversion
+    - name: Deploy docs to GitHub Pages
+      run: ./docs/_utils/deploy.sh
       env:
         GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/[email protected]

@@ -0,0 +1,27 @@
+name: "Docs / Build PR"
+
+on:
+  pull_request:
+    branches:
+    - master
+    paths:
+    - "docs/**"
+    - "topics/**"
+
+jobs:
+  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: Set up Doxygen
+      run: sudo apt-get install doxygen
+    - name: Build docs
+      run: make -C docs test

docs/Makefile

@@ -11,6 +11,8 @@ DOXYGENDIR    = ../doxygen
 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
+
 # the i18n builder cannot share the environment and doctrees with the others
 I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SOURCEDIR)
 
@@ -82,3 +84,9 @@ multiversion: setup
 .PHONY: multiversionpreview
 multiversionpreview: multiversion
 	$(POETRY) run python3 -m http.server 5500 --directory $(BUILDDIR)/dirhtml
+
+.PHONY: test
+test: setup
+	$(SPHINXBUILD) -b dirhtml $(TESTSPHINXOPTS) $(BUILDDIR)/dirhtml
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."

docs/pyproject.toml

@@ -9,7 +9,7 @@ python = "^3.7"
 pyyaml = "5.3"
 pygments = "2.2.0"
 recommonmark = "0.5.0"
-sphinx-scylladb-theme = "~0.1.11"
+sphinx-scylladb-theme = "~1.0.0"
 sphinx-sitemap = "2.1.0"
 sphinx-autobuild = "0.7.1"
 Sphinx = "2.4.4"

docs/source/conf.py

@@ -6,18 +6,12 @@
 import subprocess
 from datetime import date
 from docutils import nodes
-from sphinx.util import logging
 from recommonmark.transform import AutoStructify
 from recommonmark.parser import CommonMarkParser, splitext, urlparse
 from sphinx_scylladb_theme.utils import multiversion_regex_builder
 
-logger = logging.getLogger(__name__)
-
 # -- General configuration ------------------------------------------------
 
-# If your documentation needs a minimal Sphinx version, state it here.
-#
-needs_sphinx = '1.8'
 sys.path.insert(0, os.path.abspath('../../'))
 
 # Add any Sphinx extension module names here, as strings. They can be
@@ -86,15 +80,6 @@ def replace_relative_links(app, docname, source):
 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'2.15'
-# The full version, including alpha/beta/rc tags.
-release = u'2.15.3'
-
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 #
@@ -113,15 +98,6 @@ def replace_relative_links(app, docname, source):
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = True
 
-# Custom lexer
-from pygments.lexers.shell import BashLexer
-from sphinx.highlighting import lexers
-sys.path.insert(0, os.path.abspath('../_utils'))
-from cql import CQLLexer
-
-class DitaaLexer(BashLexer):
-    pass
-
 # Setup Sphinx
 def setup(app):
     app.add_source_parser(CustomCommonMarkParser)
@@ -141,56 +117,6 @@ def setup(app):
     app.connect('source-read', replace_relative_links)
     app.connect("builder-inited", generate_doxygen)	
 
-    #Install custom lexers
-    app.add_lexer("cql", CQLLexer())
-    app.add_lexer("ditaa", DitaaLexer())
-
-# Custom variables
-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_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': [
-    ('C/C++ Driver', 'https://cpp-driver.docs.scylladb.com/'),
-    ('Scylla Cloud', 'https://docs.scylladb.com/scylla-cloud/'),
-    ('Scylla University', 'https://university.scylladb.com/'),
-    ('ScyllaDB Home', 'https://www.scylladb.com/')],
-    'github_issues_repository': 'scylladb/cpp-driver',
-}
-
-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://cpp-driver.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 -------------------------------------------
 
@@ -255,43 +181,41 @@ def generate_doxygen(app):
     DOXYGEN_XML_DIR = breathe_projects[breathe_default_project]
     _generate_doxygen_rst(DOXYGEN_XML_DIR, app.builder.srcdir + '/api')	
 
-# -- 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 Driver Documentation',
-     u'Scylla Project Contributors', 'manual'),
-]
+# -- Options for HTML output ----------------------------------------------
 
-# -- Options for manual 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'
 
-# One entry per manual page. List of tuples
-# (source start file, name, description, authors, manual section).
-man_pages = [
-    (master_doc, 'scylladocumentation', u'Scylla Driver Documentation',
-     [author], 1)
-]
+# 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/source/',
+    'default_branch': 'master',
+    'github_repository': 'scylladb/cpp-driver',
+    'github_issues_repository': 'scylladb/cpp-driver',
+    'hide_edit_this_page_button': 'false',
+    'hide_sidebar_index': 'false'
+}
 
-# -- Options for Texinfo 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'
 
-# 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 Driver Documentation',
-     author, 'ScyllaDocumentation', 'One line description of project.',
-     'Miscellaneous'),
-]
+# Custom sidebar templates, maps document names to template names.
+#
+html_sidebars = {'**': ['side-nav.html']}
 
-# -- Options for Epub output ----------------------------------------------
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'ScyllaDocumentationdoc'
 
-# Bibliographic Dublin Core info.
-epub_title = project
-epub_author = author
-epub_publisher = author
-epub_copyright = copyright
+# URL which points to the root of the HTML documentation. 
+html_baseurl = 'https://cpp-driver.docs.scylladb.com'
 
-# 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}