Skip to content

Commit 08800b4

Browse files
dgarcia360dgarcia360
authored
Merge branch 'master' into remove-substitutions
2 parents 66b7f23 + dddd2d7 commit 08800b4

47 files changed

Lines changed: 594 additions & 533 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/codeql-analysis.yaml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,7 @@ jobs:
3838

3939
steps:
4040
- name: Checkout repository
41-
uses: actions/checkout@v2
41+
uses: actions/checkout@v3
4242

4343
# Initializes the CodeQL tools for scanning.
4444
- name: Initialize CodeQL

‎.github/workflows/docs-pages.yaml‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
name: "Docs / Publish"
22
# For more information,
3-
# see https://sphinx-theme.scylladb.com/stable/github-pages.html#available-workflows
3+
# see https://sphinx-theme.scylladb.com/stable/deployment/production.html#available-workflows
44

55
on:
66
push:
@@ -15,16 +15,16 @@ jobs:
1515
runs-on: ubuntu-latest
1616
steps:
1717
- name: Checkout
18-
uses: actions/checkout@v2
18+
uses: actions/checkout@v3
1919
with:
2020
persist-credentials: false
2121
fetch-depth: 0
2222
- name: Set up Python
23-
uses: actions/setup-python@v2.3.2
23+
uses: actions/setup-python@v3
2424
with:
2525
python-version: 3.7
26-
- name: Set up Poetry
27-
run: curl -sSL https://install.python-poetry.org | python -
26+
- name: Set up env
27+
run: make -C docs setupenv
2828
- name: Build docs
2929
run: make -C docs multiversion
3030
- name: Deploy docs to GitHub Pages

‎.github/workflows/docs-pr.yaml‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
name: "Docs / Build PR"
22
# For more information,
3-
# see https://sphinx-theme.scylladb.com/stable/github-pages.html#available-workflows
3+
# see https://sphinx-theme.scylladb.com/stable/deployment/production.html#available-workflows
44

55
on:
66
pull_request:
@@ -14,15 +14,15 @@ jobs:
1414
runs-on: ubuntu-latest
1515
steps:
1616
- name: Checkout
17-
uses: actions/checkout@v2
17+
uses: actions/checkout@v3
1818
with:
1919
persist-credentials: false
2020
fetch-depth: 0
2121
- name: Set up Python
22-
uses: actions/setup-python@v2.3.2
22+
uses: actions/setup-python@v3
2323
with:
2424
python-version: 3.7
25-
- name: Set up Poetry
26-
run: curl -sSL https://install.python-poetry.org | python -
25+
- name: Set up env
26+
run: make -C docs setupenv
2727
- name: Build docs
2828
run: make -C docs test

‎README.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ Scylla Sphinx Theme
77

88
The documentation toolchain for Scylla projects.
99

10-
.. image:: https://github.com/scylladb/sphinx-scylladb-theme/blob/master/docs/source/images/preview.png
10+
.. image:: https://github.com/scylladb/sphinx-scylladb-theme/blob/master/docs/source/deployment/images/preview.png
1111

1212
Features
1313
--------

‎docs/Makefile‎

Lines changed: 35 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -1,40 +1,46 @@
1+
# Global variables
12
# You can set these variables from the command line.
2-
POETRY = $(HOME)/.local/bin/poetry
3+
POETRY = poetry
34
SPHINXOPTS = -j auto
45
SPHINXBUILD = $(POETRY) run sphinx-build
56
PAPER =
67
BUILDDIR = _build
78
SOURCEDIR = source
89

9-
# Internal variables.
10+
# Internal variables
1011
PAPEROPT_a4 = -D latex_paper_size=a4
1112
PAPEROPT_letter = -D latex_paper_size=letter
1213
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SOURCEDIR)
1314
TESTSPHINXOPTS = $(ALLSPHINXOPTS) -W --keep-going
1415

15-
# the i18n builder cannot share the environment and doctrees with the others
16-
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SOURCEDIR)
16+
# Windows variables
17+
ifeq ($(OS),Windows_NT)
18+
POETRY = $(APPDATA)\Python\Scripts\poetry
19+
endif
1720

1821
.PHONY: all
1922
all: dirhtml
2023

21-
.PHONY: pristine
22-
pristine: clean
23-
git clean -dfX
24+
# Setup commands
25+
.PHONY: setupenv
26+
setupenv:
27+
pip install -q poetry
2428

2529
.PHONY: setup
2630
setup:
2731
$(POETRY) install
2832
$(POETRY) update
2933

34+
# Clean commands
35+
.PHONY: pristine
36+
pristine: clean
37+
git clean -dfX
38+
3039
.PHONY: clean
3140
clean:
3241
rm -rf $(BUILDDIR)/*
3342

34-
.PHONY: preview
35-
preview: setup
36-
$(POETRY) run sphinx-autobuild -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml --port 5500
37-
43+
# Generate output commands
3844
.PHONY: dirhtml
3945
dirhtml: setup
4046
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
@@ -47,40 +53,40 @@ singlehtml: setup
4753
@echo
4854
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
4955

50-
.PHONY: test
51-
test: setup
52-
$(SPHINXBUILD) -b dirhtml $(TESTSPHINXOPTS) $(BUILDDIR)/dirhtml
53-
@echo
54-
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
55-
5656
.PHONY: epub
57-
epub: setup
57+
epub: setup
5858
$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
5959
@echo
6060
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
6161

6262
.PHONY: epub3
63-
epub3: setup
63+
epub3: setup
6464
$(SPHINXBUILD) -b epub3 $(ALLSPHINXOPTS) $(BUILDDIR)/epub3
6565
@echo
6666
@echo "Build finished. The epub3 file is in $(BUILDDIR)/epub3."
6767

68-
.PHONY: dummy
69-
dummy: setup
70-
$(SPHINXBUILD) -b dummy $(ALLSPHINXOPTS) $(BUILDDIR)/dummy
71-
@echo
72-
@echo "Build finished. Dummy builder generates no files."
73-
74-
.PHONY: linkcheck
75-
linkcheck: setup
76-
$(SPHINXBUILD) -b linkcheck $(SOURCEDIR) $(BUILDDIR)/linkcheck
77-
7868
.PHONY: multiversion
7969
multiversion: setup
8070
$(POETRY) run sphinx-multiversion source $(BUILDDIR)/dirhtml
8171
@echo
8272
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
8373

74+
# Preview commands
75+
.PHONY: preview
76+
preview: setup
77+
$(POETRY) run sphinx-autobuild -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml --port 5500
78+
8479
.PHONY: multiversionpreview
8580
multiversionpreview: multiversion
8681
$(POETRY) run python -m http.server 5500 --directory $(BUILDDIR)/dirhtml
82+
83+
# Test commands
84+
.PHONY: test
85+
test: setup
86+
$(SPHINXBUILD) -b dirhtml $(TESTSPHINXOPTS) $(BUILDDIR)/dirhtml
87+
@echo
88+
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
89+
90+
.PHONY: linkcheck
91+
linkcheck: setup
92+
$(SPHINXBUILD) -b linkcheck $(SOURCEDIR) $(BUILDDIR)/linkcheck

‎docs/source/commands.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ Prerequisites
99

1010
To run the following commands, you will need to have installed **Python +3.7** and **PIP** on your local environment.
1111

12-
If you are on **Windows**, you will need to run them from a Unix-based terminal such as `Git Bash <https://www.atlassian.com/git/tutorials/git-bash>`_.
12+
.. tip:: If you are on Windows, see :ref:`How to use the toolchain in Windows <Windows_Installation>`.
1313

1414
Preview current branch
1515
----------------------

‎docs/source/configuration/troubleshooting.rst‎

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -10,17 +10,17 @@ Installation
1010
How to use the toolchain in Windows
1111
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1212

13-
To run the toolchain on **Windows**, you will need to:
13+
To run the toolchain on **Windows**:
1414

15-
1. Edit the ``POETRY`` constant in ``docs/Makefile`` to point to the ``PATH`` where you have installed Poetry.
16-
This is normally under ``C:\Users\<username>\AppData\Roaming\Python\Scripts\poetry``.
15+
#. Make sure you have `Make <https://www.gnu.org/software/make/>`_ installed.
1716

18-
.. code-block::
17+
The easiest way to install it is using Chocolatey.
18+
First, you need to `install this package manager <https://chocolatey.org/install>`_.
19+
Then, install Make with the command ``choco install make``.
1920

20-
POETRY = C:\Users\<username>\AppData\Roaming\Python\Scripts\poetry
21+
.. tip:: If you get an error when installing make, try to run the command in a console prompt with elevated permissions.
2122

22-
23-
2. Run ``make`` commands from a Unix-based terminal such as `Git Bash <https://www.atlassian.com/git/tutorials/git-bash>`_.
23+
#. You must run ``make`` commands from a Unix-based terminal such as `Git Bash <https://www.atlassian.com/git/tutorials/git-bash>`_.
2424

2525
Multiversion
2626
------------
@@ -74,7 +74,7 @@ If the console raises the error "No matching refs found!", most likely your fork
7474

7575
In this case, you can:
7676

77-
* Build multiversion docs for the upstream repository. See :ref:`Preview documentation published in production <Preview_Production>` (recommended)
78-
* Sync the fork with the upstream repository. See :ref:`Preview latest local changes <Sync_Fork>`
77+
* Build multiversion docs for the upstream repository. See :ref:`Preview documentation published in production <Preview_Production>` (recommended).
78+
* Sync the fork with the upstream repository. See :ref:`Preview latest local changes <Sync_Fork>`.
7979

8080
Another frequent mistake that raises the error message is to have typos in the configuration file. Make sure that the version names listed in ``TAGS`` and ``BRANCHES`` settings from ``conf.py`` match the repository's branch and tags names on Git.

docs/source/images/build-error.png renamed to docs/source/deployment/images/build-error.png

File renamed without changes.

docs/source/images/build-log.png renamed to docs/source/deployment/images/build-log.png

File renamed without changes.

‎docs/source/deployment/images/netlify.png‎

75.5 KB
Loading

0 commit comments

Comments
 (0)