Skip to content

Commit f09270f

Browse files
wprzytulawprzytula
authored
Migrate docs to UV (#410)
As requested by @wprzytula This is mostly the same set of changes as done in scylladb/scylla-rust-driver#1528 and scylladb/python-driver#544 For reliability and better UX, docs are migrated to use UV instead of poetry. ## Pre-review checklist <!-- Make sure you took care of the issues on the list. Put 'x' into those boxes which apply. You can also create the PR now and click on all relevant checkboxes. --> - [x] I have split my patch into logically separate commits. - [x] All commit messages clearly explain what they change and why. - [x] PR description sums up the changes and reasons why they should be introduced. - [ ] ~~I have implemented Rust unit tests for the features/changes introduced.~~ - [ ] ~~I have enabled appropriate tests in `Makefile` in `{SCYLLA,CASSANDRA}_(NO_VALGRIND_)TEST_FILTER`.~~ - [ ] ~~I added appropriate `Fixes:` annotations to PR description.~~
2 parents 866d68c + a4a882c commit f09270f

File tree

7 files changed

+1310
-1623
lines changed

7 files changed

+1310
-1623
lines changed

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

Lines changed: 10 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,10 @@ on:
66
push:
77
branches:
88
- master
9-
- 'branch-**'
9+
- "branch-**"
1010
paths:
1111
- "docs/**"
12+
- ".github/workflows/docs-pages.yaml"
1213
workflow_dispatch:
1314

1415
jobs:
@@ -21,13 +22,15 @@ jobs:
2122
ref: ${{ github.event.repository.default_branch }}
2223
persist-credentials: false
2324
fetch-depth: 0
24-
- name: Set up Python
25-
uses: actions/setup-python@v5
26-
with:
27-
python-version: '3.10'
2825

29-
- name: Set up env
30-
run: make -C docs setupenv
26+
- name: Install doxygen
27+
run: sudo apt-get update && sudo apt-get install -y doxygen
28+
29+
- name: Install uv
30+
uses: astral-sh/setup-uv@v7
31+
with:
32+
enable-cache: true
33+
cache-dependency-glob: "docs/uv.lock"
3134

3235
- name: Build docs
3336
run: make -C docs multiversion

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

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,8 @@ on:
88
- master
99
paths:
1010
- "docs/**"
11+
- ".github/workflows/docs-pr.yaml"
12+
workflow_dispatch:
1113

1214
jobs:
1315
build:
@@ -19,13 +21,14 @@ jobs:
1921
persist-credentials: false
2022
fetch-depth: 0
2123

22-
- name: Set up Python
23-
uses: actions/setup-python@v5
24+
- name: Install uv
25+
uses: astral-sh/setup-uv@v7
2426
with:
25-
python-version: '3.10'
27+
working-directory: docs
28+
enable-cache: true
2629

27-
- name: Set up env
28-
run: make -C docs setupenv
30+
- name: Install doxygen
31+
run: sudo apt-get update && sudo apt-get install -y doxygen
2932

3033
- name: Build docs
3134
run: make -C docs test

‎docs/Makefile‎

Lines changed: 8 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
# Global variables
22
# You can set these variables from the command line.
3-
POETRY = poetry
3+
UV = uv
44
SPHINXOPTS = -j auto
5-
SPHINXBUILD = $(POETRY) run sphinx-build
5+
SPHINXBUILD = $(UV) run --frozen sphinx-build
66
PAPER =
77
BUILDDIR = _build
88
SOURCEDIR = source
@@ -17,20 +17,14 @@ TESTSPHINXOPTS = $(ALLSPHINXOPTS) -W --keep-going
1717
all: dirhtml
1818

1919
# Setup commands
20-
.PHONY: setupenv
21-
setupenv:
22-
pip install -q poetry
23-
sudo apt-get install doxygen
24-
2520
.PHONY: setup
2621
setup:
27-
$(POETRY) install
28-
$(POETRY) update
22+
$(UV) sync
2923
cd .. && doxygen Doxyfile.in
3024

3125
.PHONY: update
3226
update:
33-
$(POETRY) update
27+
$(UV) lock --upgrade
3428

3529
# Clean commands
3630
.PHONY: pristine
@@ -68,24 +62,24 @@ epub3: setup
6862

6963
.PHONY: multiversion
7064
multiversion: setup
71-
$(POETRY) run sphinx-multiversion source $(BUILDDIR)/dirhtml
65+
$(UV) run --frozen sphinx-multiversion source $(BUILDDIR)/dirhtml
7266
@echo
7367
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
7468

7569
.PHONY: redirects
7670
redirects: setup
77-
$(POETRY) run redirects-cli fromfile --yaml-file _utils/redirects.yaml --output-dir $(BUILDDIR)/dirhtml
71+
$(UV) run --frozen redirects-cli fromfile --yaml-file _utils/redirects.yaml --output-dir $(BUILDDIR)/dirhtml
7872
@echo
7973
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
8074

8175
# Preview commands
8276
.PHONY: preview
8377
preview: setup
84-
$(POETRY) run sphinx-autobuild -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml --port 5500 --ignore "*/source/api/*"
78+
$(UV) run --frozen sphinx-autobuild -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml --port 5500 --ignore "*/source/api/*"
8579

8680
.PHONY: multiversionpreview
8781
multiversionpreview: multiversion
88-
$(POETRY) run python -m http.server 5500 --directory $(BUILDDIR)/dirhtml
82+
$(UV) run --frozen python -m http.server 5500 --directory $(BUILDDIR)/dirhtml
8983

9084
# Test commands
9185
.PHONY: test

‎docs/poetry.lock‎

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

‎docs/pyproject.toml‎

Lines changed: 17 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,18 @@
1-
[tool.poetry]
2-
name = "cpp-rs-driver"
3-
description = "ScyllaDB CPP RS Driver Documentation"
1+
[project]
2+
name = "cpp-rs-driver-docs"
43
version = "0.1.0"
5-
authors = ["ScyllaDB Documentation Contributors"]
6-
package-mode = false
7-
8-
[tool.poetry.dependencies]
9-
python = "^3.10"
10-
pygments = "^2.18.0"
11-
sphinx-scylladb-theme = "^1.8.10"
12-
myst-parser = "^3.0.1"
13-
sphinx-autobuild = "^2024.4.19"
14-
Sphinx = "^7.3.7"
15-
sphinx-multiversion-scylla = "^0.3.4"
16-
sphinx-sitemap = "^2.6.0"
17-
redirects_cli = "^0.1.3"
18-
breathe = "4.35.0"
19-
sphinx-scylladb-markdown = "^0.1.2"
20-
21-
[build-system]
22-
requires = ["poetry>=1.8.0"]
23-
build-backend = "poetry.masonry.api"
4+
description = "ScyllaDB CPP RS Driver Documentation"
5+
authors = [{ name = "ScyllaDB Documentation Contributors" }]
6+
requires-python = ">=3.10"
7+
dependencies = [
8+
"pygments>=2.18.0",
9+
"sphinx-scylladb-theme>=1.8.10",
10+
"myst-parser>=3.0.1",
11+
"sphinx-autobuild>=2024.4.19",
12+
"sphinx>=7.3.7",
13+
"sphinx-multiversion-scylla>=0.3.4",
14+
"sphinx-sitemap>=2.6.0",
15+
"redirects-cli>=0.1.3",
16+
"breathe==4.35.0",
17+
"sphinx-scylladb-markdown>=0.1.2",
18+
]

‎docs/source/conf.py‎

Lines changed: 34 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -38,8 +38,8 @@
3838
"sphinx_scylladb_theme",
3939
"sphinx_multiversion", # optional
4040
"myst_parser", # optional
41-
'breathe',
42-
'sphinx_scylladb_markdown',
41+
"breathe",
42+
"sphinx_scylladb_markdown",
4343
]
4444

4545
# The suffix(es) of source filenames.
@@ -55,7 +55,7 @@
5555

5656
# List of patterns, relative to source directory, that match files and
5757
# directories to ignore when looking for source files.
58-
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
58+
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", ".venv"]
5959

6060
# The name of the Pygments (syntax highlighting) style to use.
6161
pygments_style = "sphinx"
@@ -100,43 +100,55 @@
100100

101101

102102
# -- Options for Doxygen (API Reference)
103-
breathe_projects = {
104-
'API': "../../doxygen/xml/"
105-
}
106-
breathe_default_project = 'API'
107-
breathe_default_members = ('members', 'undoc-members')
103+
breathe_projects = {"API": "../../doxygen/xml/"}
104+
breathe_default_project = "API"
105+
breathe_default_members = ("members", "undoc-members")
108106

109107
# Hide parent class names in sidebar
110-
toc_object_entries_show_parents = 'hide'
108+
toc_object_entries_show_parents = "hide"
109+
111110

112111
# Autogenerate API reference
113112
def _generate_structs(outdir, structs, project):
114113
"""Write structs docs in the designated outdir folder"""
115114
for obj in structs:
116-
with open(outdir + '/struct.' + obj + '.rst', 'w') as t_file:
117-
t_file.write(obj + "\n" + "=" * len(obj) + "\n\n" + ".. doxygenstruct:: " + obj +" \n :project: " + project)
115+
with open(outdir + "/struct." + obj + ".rst", "w") as t_file:
116+
t_file.write(
117+
obj
118+
+ "\n"
119+
+ "=" * len(obj)
120+
+ "\n\n"
121+
+ ".. doxygenstruct:: "
122+
+ obj
123+
+ " \n :project: "
124+
+ project
125+
)
126+
118127

119128
def _generate_doxygen_rst(xmldir, outdir):
120129
"""Autogenerate doxygen docs in the designated outdir folder"""
121130
structs = []
122131
files = os.listdir(os.path.join(os.path.dirname(__file__), xmldir))
123132
for file_name in files:
124-
if 'struct' in file_name and '__' not in file_name:
125-
structs.append(file_name
126-
.replace('struct_', '')
127-
.replace('_', ' ')
128-
.replace('.xml','')
129-
.title()
130-
.replace(' ', ''))
133+
if "struct" in file_name and "__" not in file_name:
134+
structs.append(
135+
file_name.replace("struct_", "")
136+
.replace("_", " ")
137+
.replace(".xml", "")
138+
.title()
139+
.replace(" ", "")
140+
)
131141
_generate_structs(outdir, structs, breathe_default_project)
132142

143+
133144
def generate_doxygen(app):
134145
DOXYGEN_XML_DIR = breathe_projects[breathe_default_project]
135-
_generate_doxygen_rst(DOXYGEN_XML_DIR, app.builder.srcdir + '/api')
146+
_generate_doxygen_rst(DOXYGEN_XML_DIR, app.builder.srcdir + "/api")
147+
136148

137149
# -- Options for sitemap extension
138150

139-
sitemap_url_scheme = '/stable/{link}'
151+
sitemap_url_scheme = "/stable/{link}"
140152

141153
# The theme to use for pages.
142154
html_theme = "sphinx_scylladb_theme"
@@ -168,13 +180,14 @@ def generate_doxygen(app):
168180
htmlhelp_basename = "ScyllaDocumentationdoc"
169181

170182
# URL which points to the root of the HTML documentation.
171-
html_baseurl = 'https://cpp-rs-driver.docs.scylladb.com'
183+
html_baseurl = "https://cpp-rs-driver.docs.scylladb.com"
172184

173185
# Dictionary of values to pass into the template engine’s context for all pages
174186
html_context = {"html_baseurl": html_baseurl}
175187

176188
# -- Initialize Sphinx ----------------------------------------------
177189

190+
178191
def setup(sphinx):
179192
warnings.filterwarnings(
180193
action="ignore",

0 commit comments

Comments
 (0)