diff --git a/.github/workflows/docs-pages.yaml b/.github/workflows/docs-pages.yaml new file mode 100644 index 0000000000..b9b40fc262 --- /dev/null +++ b/.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 }} \ No newline at end of file diff --git a/.github/workflows/docs-pages@v2.yaml b/.github/workflows/docs-pages@v2.yaml deleted file mode 100644 index 5738b147c9..0000000000 --- a/.github/workflows/docs-pages@v2.yaml +++ /dev/null @@ -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 }} diff --git a/.github/workflows/docs-pr.yaml b/.github/workflows/docs-pr.yaml new file mode 100644 index 0000000000..afb345b333 --- /dev/null +++ b/.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 \ No newline at end of file diff --git a/.github/workflows/docs-pr@v1.yaml b/.github/workflows/docs-pr@v1.yaml deleted file mode 100644 index c74a3f8737..0000000000 --- a/.github/workflows/docs-pr@v1.yaml +++ /dev/null @@ -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 diff --git a/docs/Makefile b/docs/Makefile index 3ddcdf06a9..c7a4a08de6 100644 --- a/docs/Makefile +++ b/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 diff --git a/docs/_utils/setup.sh b/docs/_utils/setup.sh deleted file mode 100755 index ec22cd3f72..0000000000 --- a/docs/_utils/setup.sh +++ /dev/null @@ -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 diff --git a/docs/conf.py b/docs/conf.py index 6dba6c7db4..0894c22c60 100644 --- a/docs/conf.py +++ b/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) + diff --git a/docs/contents.rst b/docs/contents.rst index dee5be65e5..bd1ce13ea0 100644 --- a/docs/contents.rst +++ b/docs/contents.rst @@ -7,4 +7,3 @@ design-notes/index guides/index contribute/index - service_levels \ No newline at end of file diff --git a/docs/pyproject.toml b/docs/pyproject.toml index 6f7002f5ab..e9c76b67cb 100644 --- a/docs/pyproject.toml +++ b/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"]