Checkout current docs setup from scylla-4.x branch

Main motivation is getting myst parser in, so that documentation builds
correctly for this version.
Brings several changes that are in scylla-4.x as of commit
c85f7b9

Author: Bouncheck

docs/Makefile

@@ -1,89 +1,108 @@
 # You can set these variables from the command line.
-POETRY        = $(HOME)/.poetry/bin/poetry
-SPHINXOPTS    =
+POETRY        = poetry
+SPHINXOPTS    = -j auto
 SPHINXBUILD   = $(POETRY) run sphinx-build
 PAPER         =
 BUILDDIR      = _build
-SOURCE_DIR    = _source
+SOURCEDIR     = _source
 
-# Internal variables.
+# Internal variables
 PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SOURCE_DIR)
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SOURCEDIR)
 TESTSPHINXOPTS  = $(ALLSPHINXOPTS) -W --keep-going
-
-# the i18n builder cannot share the environment and doctrees with the others
-I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SOURCEDIR)
 
 .PHONY: all
 all: dirhtml
 
+# Setup commands
+.PHONY: setupenv
+setupenv:
+	pip install -q poetry
+
+.PHONY: setup
+setup:
+	$(POETRY) install
+	@if [ ! -d "$(SOURCEDIR)" ]; then mkdir -p "$(SOURCEDIR)"; fi
+	cp -RL source/* $(SOURCEDIR)
+	cd $(SOURCEDIR) && find . -name README.md -execdir mv '{}' index.md ';'
+
+.PHONY: update
+update:
+	$(POETRY) update
+
+# Clean commands
 .PHONY: pristine
 pristine: clean
 	git clean -dfX
 
-.PHONY: setup
-setup:
-	./_utils/setup.sh
-	cp -TLr source $(SOURCE_DIR)
-	cd $(SOURCE_DIR) && find . -name README.md -execdir mv '{}' index.md ';'
 .PHONY: clean
 clean:
 	rm -rf $(BUILDDIR)/*
-	rm -rf $(SOURCE_DIR)/*
-
-.PHONY: preview
-preview: setup
-	cd .. && ./docs/_utils/javadoc.sh
-	$(POETRY) run sphinx-autobuild -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml --port 5500
+	rm -rf $(SOURCEDIR)/*
+	rm -f poetry.lock
 
+# Generate output commands
 .PHONY: dirhtml
 dirhtml: setup
+	@$(javadoc)
 	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
 
-.PHONY: singlehtml
-singlehtml: setup
-	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+.PHONY: javadoc
+javadoc: setup
+	cd .. && ./docs/_utils/javadoc.sh
 	@echo
 	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
 
+.PHONY: multiversion
+multiversion: setup
+	$(POETRY) run ./_utils/multiversion.sh
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
 .PHONY: epub
-epub: 	setup
+epub: setup
 	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
 	@echo
 	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
 
 .PHONY: epub3
-epub3:	setup
+epub3:setup
 	$(SPHINXBUILD) -b epub3 $(ALLSPHINXOPTS) $(BUILDDIR)/epub3
 	@echo
 	@echo "Build finished. The epub3 file is in $(BUILDDIR)/epub3."
 
 .PHONY: dummy
-dummy: 	setup
+dummy: setup
 	$(SPHINXBUILD) -b dummy $(ALLSPHINXOPTS) $(BUILDDIR)/dummy
 	@echo
 	@echo "Build finished. Dummy builder generates no files."
 
-.PHONY: linkcheck
-linkcheck: setup
-	$(SPHINXBUILD) -b linkcheck $(SOURCE_DIR) $(BUILDDIR)/linkcheck
-
-.PHONY: multiversion
-multiversion: setup
-	@mkdir -p $(HOME)/.cache/pypoetry/virtualenvs
-	$(POETRY) run ./_utils/multiversion.sh
-	@echo
-	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+# Preview commands
+.PHONY: preview
+preview: setup
+	$(POETRY) run sphinx-autobuild -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml --port 5500 --re-ignore 'api/*'
 
 .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: redirects
+redirects: setup
+	$(POETRY) run redirects-cli fromfile --yaml-file _utils/redirects.yaml --output-dir $(BUILDDIR)/dirhtml
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
 
+# Test commands
 .PHONY: test
 test: setup
 	$(SPHINXBUILD) -b dirhtml $(TESTSPHINXOPTS) $(BUILDDIR)/dirhtml
 	@echo
-	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+.PHONY: linkcheck
+linkcheck: setup
+	$(SPHINXBUILD) -b linkcheck $(SOURCEDIR) $(BUILDDIR)/linkcheck

docs/_utils/deploy.sh

@@ -0,0 +1,18 @@
+#!/bin/bash
+
+# Copy contents
+mkdir gh-pages
+cp -r ./docs/_build/dirhtml/. gh-pages
+
+# Create gh-pages branch
+cd gh-pages
+git init
+git config --local user.email "[email protected]"
+git config --local user.name "GitHub Action"
+git remote add origin "https://x-access-token:${GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}.git"
+git checkout -b gh-pages
+
+# Deploy
+git add .
+git commit -m "Publish docs" || true
+git push origin gh-pages --force

docs/_utils/javadoc.sh

@@ -1,7 +1,7 @@
 #!/bin/bash
 
 # Install dependencies
-mvn install -DskipTests
+mvn install -DskipTests -T 1C
 
 # Define output folder
 OUTPUT_DIR="docs/_build/dirhtml/api"
@@ -11,7 +11,7 @@ if [[ "$SPHINX_MULTIVERSION_OUTPUTDIR" != "" ]]; then
 fi
 
 # Generate javadoc
-mvn javadoc:javadoc
+mvn javadoc:javadoc -T 1C
 [ -d $OUTPUT_DIR ] && rm -r $OUTPUT_DIR
 mkdir -p "$OUTPUT_DIR"
-mv -f core/target/site/apidocs/* $OUTPUT_DIR
+mv -f driver-core/target/site/apidocs/* $OUTPUT_DIR

docs/_utils/multiversion.sh

@@ -1,5 +1,5 @@
 #! /bin/bash	
 
 cd .. && sphinx-multiversion docs/source docs/_build/dirhtml \
-    --pre-build './docs/_utils/javadoc.sh' \
-    --pre-build "find . -mindepth 2 -name README.md -execdir mv '{}' index.md ';'"
+    --pre-build "find . -mindepth 2 -name README.md -execdir mv '{}' index.md ';'" \
+    --post-build './docs/_utils/javadoc.sh'