Skip to content

Commit 0b5ae07

Browse files
dgarcia360tchaikov
dgarcia360
authored and
tchaikov
committed
docs: update theme 1.2
docs: update dynamic slug Add back index.md Move custom slug to a separate PR Fix typo (cherry picked from commit 8feeb20)
1 parent f64ab35 commit 0b5ae07

File tree

9 files changed

+174
-107
lines changed

9 files changed

+174
-107
lines changed

‎.github/workflows/docs-pages.yaml

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
name: "Docs / Publish"
2+
# For more information,
3+
# see https://sphinx-theme.scylladb.com/stable/deployment/production.html#available-workflows
4+
5+
on:
6+
push:
7+
branches:
8+
- scylla-3.x
9+
paths:
10+
- 'docs/**'
11+
- 'faq/**'
12+
- 'manual/**'
13+
- 'changelog/**'
14+
- 'upgrade_guide/**'
15+
workflow_dispatch:
16+
17+
jobs:
18+
release:
19+
runs-on: ubuntu-latest
20+
steps:
21+
- name: Checkout
22+
uses: actions/checkout@v3
23+
with:
24+
persist-credentials: false
25+
fetch-depth: 0
26+
- name: Set up Python
27+
uses: actions/setup-python@v3
28+
with:
29+
python-version: 3.7
30+
- name: Set up JDK 1.8
31+
uses: actions/setup-java@v1
32+
with:
33+
java-version: 1.8
34+
- name: Set up env
35+
run: make -C docs setupenv
36+
- name: Build docs
37+
run: make -C docs multiversion
38+
- name: Deploy docs to GitHub Pages
39+
run: ./docs/_utils/deploy.sh
40+
env:
41+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

‎.github/workflows/docs-pr.yaml

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
name: "Docs / Build PR"
2+
# For more information,
3+
# see https://sphinx-theme.scylladb.com/stable/deployment/production.html#available-workflows
4+
5+
on:
6+
pull_request:
7+
branches:
8+
- scylla-3.x
9+
paths:
10+
- 'docs/**'
11+
- 'faq/**'
12+
- 'manual/**'
13+
- 'changelog/**'
14+
- 'upgrade_guide/**'
15+
16+
jobs:
17+
build:
18+
runs-on: ubuntu-latest
19+
steps:
20+
- name: Checkout
21+
uses: actions/checkout@v3
22+
with:
23+
persist-credentials: false
24+
fetch-depth: 0
25+
- name: Set up Python
26+
uses: actions/setup-python@v3
27+
with:
28+
python-version: 3.7
29+
- name: Set up JDK 1.8
30+
uses: actions/setup-java@v1
31+
with:
32+
java-version: 1.8
33+
- name: Set up env
34+
run: make -C docs setupenv
35+
- name: Build docs
36+
run: make -C docs test

‎README-dev.md

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# Building the docs
2+
3+
The docs build instructions have been tested with Sphinx 4 and Fedora 32.
4+
5+
## Prerequisites
6+
7+
To build and preview the docs locally, you will need to install the following software:
8+
9+
- Git
10+
- Python 3.7
11+
- pip
12+
- Java JDK 8 or above
13+
- Maven
14+
15+
## Commands
16+
17+
For more information, see [Commands](https://sphinx-theme.scylladb.com/stable/commands.html).

‎docs.yaml

Lines changed: 0 additions & 43 deletions
This file was deleted.

‎docs/Makefile

Lines changed: 50 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -1,89 +1,107 @@
11
# You can set these variables from the command line.
2-
POETRY = $(HOME)/.poetry/bin/poetry
2+
POETRY = poetry
33
SPHINXOPTS =
44
SPHINXBUILD = $(POETRY) run sphinx-build
55
PAPER =
66
BUILDDIR = _build
7-
SOURCE_DIR = _source
7+
SOURCEDIR = _source
88

9-
# Internal variables.
9+
# Internal variables
1010
PAPEROPT_a4 = -D latex_paper_size=a4
1111
PAPEROPT_letter = -D latex_paper_size=letter
12-
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SOURCE_DIR)
12+
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SOURCEDIR)
1313
TESTSPHINXOPTS = $(ALLSPHINXOPTS) -W --keep-going
14+
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SOURCEDIR)
1415

15-
# the i18n builder cannot share the environment and doctrees with the others
16-
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
16+
# Windows variables
17+
ifeq ($(OS),Windows_NT)
18+
POETRY = $(APPDATA)\Python\Scripts\poetry
19+
endif
20+
21+
define javadoc
22+
cd .. && ./docs/_utils/javadoc.sh
23+
endef
1724

1825
.PHONY: all
1926
all: dirhtml
2027

28+
# Setup commands
29+
.PHONY: setupenv
30+
setupenv:
31+
pip install -q poetry
32+
33+
.PHONY: setup
34+
setup:
35+
$(POETRY) install
36+
$(POETRY) update
37+
cp -TLr source $(SOURCEDIR)
38+
cd $(SOURCEDIR) && find . -name README.md -execdir mv '{}' index.md ';'
39+
40+
# Clean commands
2141
.PHONY: pristine
2242
pristine: clean
2343
git clean -dfX
2444

25-
.PHONY: setup
26-
setup:
27-
./_utils/setup.sh
28-
cp -TLr source $(SOURCE_DIR)
29-
cd $(SOURCE_DIR) && find . -name README.md -execdir mv '{}' index.md ';'
3045
.PHONY: clean
3146
clean:
3247
rm -rf $(BUILDDIR)/*
33-
rm -rf $(SOURCE_DIR)/*
34-
35-
.PHONY: preview
36-
preview: setup
37-
cd .. && ./docs/_utils/javadoc.sh
38-
$(POETRY) run sphinx-autobuild -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml --port 5500
48+
rm -rf $(SOURCEDIR)/*
3949

50+
# Generate output commands
4051
.PHONY: dirhtml
4152
dirhtml: setup
53+
@$(javadoc)
4254
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
4355
@echo
4456
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
4557

4658
.PHONY: singlehtml
4759
singlehtml: setup
60+
@$(javadoc)
4861
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
4962
@echo
5063
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
5164

65+
.PHONY: multiversion
66+
multiversion: setup
67+
$(POETRY) run ./_utils/multiversion.sh
68+
@echo
69+
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
70+
5271
.PHONY: epub
53-
epub: setup
72+
epub: setup
5473
$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
5574
@echo
5675
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
5776

5877
.PHONY: epub3
59-
epub3: setup
78+
epub3:setup
6079
$(SPHINXBUILD) -b epub3 $(ALLSPHINXOPTS) $(BUILDDIR)/epub3
6180
@echo
6281
@echo "Build finished. The epub3 file is in $(BUILDDIR)/epub3."
6382

6483
.PHONY: dummy
65-
dummy: setup
84+
dummy: setup
6685
$(SPHINXBUILD) -b dummy $(ALLSPHINXOPTS) $(BUILDDIR)/dummy
6786
@echo
6887
@echo "Build finished. Dummy builder generates no files."
6988

70-
.PHONY: linkcheck
71-
linkcheck: setup
72-
$(SPHINXBUILD) -b linkcheck $(SOURCE_DIR) $(BUILDDIR)/linkcheck
73-
74-
.PHONY: multiversion
75-
multiversion: setup
76-
@mkdir -p $(HOME)/.cache/pypoetry/virtualenvs
77-
$(POETRY) run ./_utils/multiversion.sh
78-
@echo
79-
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
89+
# Preview commands
90+
.PHONY: preview
91+
preview: setup
92+
$(POETRY) run sphinx-autobuild -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml --port 5500 --re-ignore 'api/*'
8093

8194
.PHONY: multiversionpreview
8295
multiversionpreview: multiversion
83-
$(POETRY) run python3 -m http.server 5500 --directory $(BUILDDIR)/dirhtml
96+
$(POETRY) run python -m http.server 5500 --directory $(BUILDDIR)/dirhtml
8497

98+
# Test commands
8599
.PHONY: test
86100
test: setup
87101
$(SPHINXBUILD) -b dirhtml $(TESTSPHINXOPTS) $(BUILDDIR)/dirhtml
88102
@echo
89-
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
103+
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
104+
105+
.PHONY: linkcheck
106+
linkcheck: setup
107+
$(SPHINXBUILD) -b linkcheck $(SOURCEDIR) $(BUILDDIR)/linkcheck

‎docs/_utils/javadoc.sh

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
#!/bin/bash
22

33
# Install dependencies
4-
mvn install -DskipTests
4+
mvn install -DskipTests -T 1C
55

66
# Define output folder
77
OUTPUT_DIR="docs/_build/dirhtml/api"
@@ -11,7 +11,7 @@ if [[ "$SPHINX_MULTIVERSION_OUTPUTDIR" != "" ]]; then
1111
fi
1212

1313
# Generate javadoc
14-
mvn javadoc:javadoc
14+
mvn javadoc:javadoc -T 1C
1515
[ -d $OUTPUT_DIR ] && rm -r $OUTPUT_DIR
1616
mkdir -p "$OUTPUT_DIR"
1717
mv -f core/target/site/apidocs/* $OUTPUT_DIR

‎docs/_utils/setup.sh

Lines changed: 0 additions & 11 deletions
This file was deleted.

‎docs/pyproject.toml

Lines changed: 6 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -6,18 +6,14 @@ authors = ["Java Driver Contributors"]
66

77
[tool.poetry.dependencies]
88
python = "^3.7"
9-
pyyaml = "5.3"
9+
pyyaml = "6.0"
1010
pygments = "2.2.0"
11-
recommonmark = "0.5.0"
12-
sphinx-scylladb-theme = "~1.0.0"
11+
recommonmark = "0.7.1"
12+
sphinx-scylladb-theme = "~1.2.1"
1313
sphinx-sitemap = "2.1.0"
14-
sphinx-autobuild = "0.7.1"
15-
Sphinx = "2.4.4"
16-
sphinx-multiversion-scylla = "~0.2.6"
17-
Jinja2 = "<3.1"
18-
19-
[tool.poetry.dev-dependencies]
20-
pytest = "5.2"
14+
sphinx-autobuild = "2021.3.14"
15+
Sphinx = "4.3.2"
16+
sphinx-multiversion-scylla = "~0.2.11"
2117

2218
[build-system]
2319
requires = ["poetry>=0.12"]

0 commit comments

Comments
 (0)