Merge 'docs: update theme 1.1' from David Garcia

Related issue https://github.com/scylladb/sphinx-scylladb-theme/issues/310

ScyllaDB Sphinx Theme 1.1 is now released 🥳

We’ve made a number of updates to update all our dependencies to the latest version and introduced new directives you can use to write great docs.

You can read more about all notable changes [here](https://sphinx-theme.scylladb.com/master/upgrade/CHANGELOG.html#february-2022).

Before,  the theme installed [poetry 1.1.x](https://python-poetry.org/) as a dependency to manage Python dependencies. However, ``poetry 1.2.x`` changed the installation method. Therefore, we've decided to [#307 Make poetry a prerequisite](https://github.com/scylladb/sphinx-scylladb-theme/issues/307) so that you can decide to install the poetry version you prefer.

To preview the docs locally, you should uninstall the previous version of poetry. Then, install the latest version:

1. Uninstall Poetry 1.1.x.

```
curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py | POETRY_UNINSTALL=1 python -
```

2. Install Poetry 1.2.x. For detailed instructions, see [Poetry installation](https://python-poetry.org/docs/master/#installation).

1. Clone this PR. For more information, see [Cloning pull requests locally](https://docs.github.com/en/github/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/checking-out-pull-requests-locally).

2. Uninstall poetry 1.1 and install poetry 1.2. For more information, see **Breaking changes** notice above.

3. Enter the docs folder, and run:

```
make preview
````

4. Open http://127.0.0.1:5500/ with your favorite browser. The doc should render without errors, and the version should be Sphinx Theme version (see the footer) must be ``1.1.x``:

![image](https://user-images.githubusercontent.com/9107969/152107446-52b167d8-c607-4431-a7a4-92579153d024.png)

Closes #10054

* github.com:scylladb/scylla:
  Add missing lexer
  docs: update theme 1.1

.github/workflows/docs-pages.yaml

@@ -0,0 +1,31 @@
+name: "Docs / Publish"
+
+on:
+  push:
+    branches:
+      - master
+    paths:
+      - "docs/**"
+  workflow_dispatch:
+
+jobs:
+  release:
+    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@v2.3.2
+        with:
+          python-version: 3.7
+      - name: Set up Poetry
+        run: curl -sSL https://install.python-poetry.org | python -
+      - name: Build docs
+        run: make -C docs multiversion
+      - name: Deploy docs to GitHub Pages
+        run: ./docs/_utils/deploy.sh
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/docs-pages@v2.yaml

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

.github/workflows/docs-pr.yaml

@@ -0,0 +1,26 @@
+name: "Docs / Build PR"
+
+on:
+  pull_request:
+    branches:
+      - master
+    paths:
+      - "docs/**"
+
+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@v2.3.2
+        with:
+          python-version: 3.7
+      - name: Set up Poetry
+        run: curl -sSL https://install.python-poetry.org | python -
+      - name: Build docs
+        run: make -C docs test

.github/workflows/docs-pr@v1.yaml

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

docs/Makefile

@@ -1,5 +1,5 @@
 # You can set these variables from the command line.
-POETRY        := $(HOME)/.poetry/bin/poetry
+POETRY        := $(HOME)/.local/bin/poetry
 SPHINXBUILD   := $(POETRY) run sphinx-build
 SPHINXOPTS    :=
 PAPER         :=
@@ -24,7 +24,8 @@ pristine: clean
 
 .PHONY: setup
 setup:
-	./_utils/setup.sh
+	$(POETRY) install
+	$(POETRY) update
 
 .PHONY: clean
 clean:
@@ -70,14 +71,13 @@ linkcheck: setup
 
 .PHONY: multiversion
 multiversion: setup
-	@mkdir -p $(HOME)/.cache/pypoetry/virtualenvs
 	$(POETRY) run sphinx-multiversion $(SOURCEDIR) $(BUILDDIR)/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 
+	$(POETRY) run python -m http.server 5500 --directory $(BUILDDIR)/dirhtml 
 
 .PHONY: test
 test: setup

docs/_utils/setup.sh

@@ -1,11 +0,0 @@
-#!/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

docs/conf.py

@@ -4,6 +4,7 @@ import sys
 from datetime import date
 import recommonmark
 from recommonmark.transform import AutoStructify
+from pygments.lexers.javascript import JavascriptLexer
 from sphinx_scylladb_theme.utils import multiversion_regex_builder
 
 sys.path.insert(0, os.path.abspath('..'))
@@ -46,17 +47,6 @@ exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'README.md', '_utils']
 # 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)
-
 # -- Options for not found extension -------------------------------------------
 
 # Template used to render the 404.html generated by this extension.
@@ -105,7 +95,6 @@ html_theme_options = {
     'github_repository': 'scylladb/scylla',
     'github_issues_repository': 'scylladb/scylla',
     'hide_edit_this_page_button': 'false',
-    'hide_sidebar_index': 'false',
     'hide_version_dropdown': ['master'],
 }
 
@@ -127,3 +116,20 @@ 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}
+
+
+class AssemblyScriptLexer(JavascriptLexer):
+    pass
+
+# Setup Sphinx
+def setup(sphinx):
+    # Add Markdown support
+    sphinx.add_config_value('recommonmark_config', {
+        'enable_eval_rst': True,
+        'enable_auto_toc_tree': False,
+    }, True)
+    sphinx.add_transform(AutoStructify)
+    
+    # Custom lexers
+    sphinx.add_lexer("assemblyscript", AssemblyScriptLexer)
+

docs/contents.rst

@@ -7,4 +7,3 @@
     design-notes/index
     guides/index
     contribute/index
-    service_levels

docs/pyproject.toml

@@ -6,17 +6,15 @@ authors = ["ScyllaDB Contributors"]
 
 [tool.poetry.dependencies]
 python = "^3.7"
-pyyaml = "5.3"
+pyyaml = "^6.0"
 pygments = "2.2.0"
-recommonmark = "0.5.0"
-sphinx-scylladb-theme = "~1.0.0"
+recommonmark = "^0.7.1"
+sphinx-scylladb-theme = "~1.1.0"
 sphinx-sitemap = "2.1.0"
-sphinx-autobuild = "0.7.1"
-Sphinx = "2.4.4"
-sphinx-multiversion-scylla = "~0.2.6"
+sphinx-autobuild = "^2021.3.14"
+Sphinx = "^4.3.2"
+sphinx-multiversion-scylla = "~0.2.10"
 sphinx-markdown-tables = "0.0.15"
-[tool.poetry.dev-dependencies]
-pytest = "5.2"
 
 [build-system]
 requires = ["poetry>=0.12"]