Skip to content

Commit 32276df

Browse files
dgarcia360dgarcia360
committed
Docs automation
Update README-dev.rst Prefer warnings Updated CHANGELOG Import README from original file Rollback spaces Fix spaces Fix spaces
1 parent 3aec70d commit 32276df

27 files changed

+1450
-17
lines changed

‎.github/workflows/pages.yml

+34
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
name: "CI Docs"
2+
3+
on:
4+
push:
5+
branches:
6+
- latest
7+
tags:
8+
- '**'
9+
jobs:
10+
release:
11+
name: Build
12+
runs-on: ubuntu-latest
13+
steps:
14+
- name: Checkout
15+
uses: actions/checkout@v2
16+
with:
17+
persist-credentials: false
18+
fetch-depth: 0
19+
- name: Set up Python
20+
uses: actions/setup-python@v1
21+
with:
22+
python-version: 3.7
23+
- name: Set up Doxygen
24+
run: sudo apt-get install doxygen
25+
- name: Build Sphinx docs
26+
run: |
27+
export PATH=$PATH:~/.local/bin
28+
cd docs
29+
make multiversion
30+
- name: Deploy
31+
run : ./docs/_utils/deploy.sh
32+
env:
33+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
34+
LATEST_VERSION: latest

‎.gitignore

+4-2
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,10 @@ testing/
44
.settings
55
.classpath
66
.project
7-
doc
8-
docs
7+
docs/_build
8+
docs/_source
9+
html
10+
latex
911
notes
1012
.DS_Store
1113

‎README-dev.rst

+36
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
Building the Docs
2+
=================
3+
4+
*Note*: The docs build instructions have been tested with Sphinx 2.4.4 and Fedora 32.
5+
6+
To build and preview the docs locally, you will need to install the following software:
7+
8+
- `Git <https://git-scm.com/book/en/v2/Getting-Started-Installing-Git>`_
9+
- `Python 3.7 <https://www.python.org/downloads/>`_
10+
- `pip <https://pip.pypa.io/en/stable/installing/>`_
11+
- `doxygen <https://www.tutorialspoint.com/how-to-install-doxygen-on-ubuntu/>`_
12+
13+
Run the following command to build the docs.
14+
15+
.. code:: console
16+
17+
cd docs
18+
make preview
19+
20+
Once the command completes processing, open http://127.0.0.1:5500/ with your preferred browser.
21+
22+
Building multiple documentation versions
23+
========================================
24+
25+
Build Sphinx docs for all the versions defined in ``docs/conf.py``.
26+
27+
The multiverson command does not build doxygen docs.
28+
29+
.. code:: console
30+
31+
cd docs
32+
make multiversion
33+
34+
Then, open ``docs/_build/dirhtml/<version>/index.html`` with your preferred browser.
35+
36+
**NOTE:** If you only can see docs generated for the master branch, try to run ``git fetch --tags`` to download the latest tags from remote.

‎changelog/README.md

+7-8
Original file line numberDiff line numberDiff line change
@@ -5,25 +5,25 @@
55
3.x versions get published.
66
-->
77

8-
## 3.10.1
8+
### 3.10.1
99

1010
- [bug] JAVA-2857: Fix NPE when built statements without parameters are logged at TRACE level.
1111
- [bug] JAVA-2843: Successfully parse DSE table schema in OSS driver.
1212

13-
## 3.10.0
13+
### 3.10.0
1414

1515
- [improvement] JAVA-2676: Don't reschedule flusher after empty runs
1616
- [new feature] JAVA-2772: Support new protocol v5 message format
1717

18-
## 3.9.0
18+
### 3.9.0
1919

2020
- [bug] JAVA-2627: Avoid logging error message including stack trace in request handler.
2121
- [new feature] JAVA-2706: Add now_in_seconds to protocol v5 query messages.
2222
- [improvement] JAVA-2730: Add support for Cassandra® 4.0 table options
2323
- [improvement] JAVA-2702: Transient Replication Support for Cassandra® 4.0
2424

2525

26-
## 3.8.0
26+
### 3.8.0
2727

2828
- [new feature] JAVA-2356: Support for DataStax Cloud API.
2929
- [improvement] JAVA-2483: Allow to provide secure bundle via URL.
@@ -48,10 +48,9 @@
4848
- [bug] JAVA-2174: Metadata.needsQuote should accept empty strings.
4949
- [bug] JAVA-2193: Fix flaky tests in WarningsTest.
5050

51-
5251
### 3.7.0
5352

54-
- [improvement] JAVA-2025: Include exception message in Abstract\*Codec.accepts(null).
53+
- [improvement] JAVA-2025: Include exception message in Abstract*Codec.accepts(null).
5554
- [improvement] JAVA-1980: Use covariant return types in RemoteEndpointAwareJdkSSLOptions.Builder methods.
5655
- [documentation] JAVA-2062: Document frozen collection preference with Mapper.
5756
- [bug] JAVA-2071: Fix NPE in ArrayBackedRow.toString().
@@ -80,13 +79,13 @@
8079
- [bug] JAVA-1924: StatementWrapper setters should return the wrapping statement.
8180
- [new feature] JAVA-1532: Add Codec support for Java 8's LocalDateTime and ZoneId.
8281
- [improvement] JAVA-1786: Use Google code formatter.
83-
- [bug] JAVA-1871: Change LOCAL\_SERIAL.isDCLocal() to return true.
82+
- [bug] JAVA-1871: Change LOCAL_SERIAL.isDCLocal() to return true.
8483
- [documentation] JAVA-1902: Clarify unavailable & request error in DefaultRetryPolicy javadoc.
8584
- [new feature] JAVA-1903: Add WhiteListPolicy.ofHosts.
8685
- [bug] JAVA-1928: Fix GuavaCompatibility for Guava 26.
8786
- [bug] JAVA-1935: Add null check in QueryConsistencyException.getHost.
8887
- [improvement] JAVA-1771: Send driver name and version in STARTUP message.
89-
- [improvement] JAVA-1388: Add dynamic port discovery for system.peers\_v2.
88+
- [improvement] JAVA-1388: Add dynamic port discovery for system.peers_v2.
9089
- [documentation] JAVA-1810: Note which setters are not propagated to PreparedStatement.
9190
- [bug] JAVA-1944: Surface Read and WriteFailureException to RetryPolicy.
9291
- [bug] JAVA-1211: Fix NPE in cluster close when cluster init fails.

‎docs/Makefile

+76
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
# You can set these variables from the command line.
2+
SPHINXOPTS =
3+
SPHINXBUILD = poetry run sphinx-build
4+
PAPER =
5+
BUILDDIR = _build
6+
SOURCE_DIR = _source
7+
8+
# Internal variables.
9+
PAPEROPT_a4 = -D latex_paper_size=a4
10+
PAPEROPT_letter = -D latex_paper_size=letter
11+
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SOURCE_DIR)
12+
# the i18n builder cannot share the environment and doctrees with the others
13+
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
14+
15+
.PHONY: all
16+
all: dirhtml
17+
18+
.PHONY: pristine
19+
pristine: clean
20+
git clean -dfX
21+
22+
.PHONY: setup
23+
setup:
24+
./_utils/setup.sh
25+
cp -Tr source $(SOURCE_DIR)
26+
cd $(SOURCE_DIR) && find -name README.md -execdir mv '{}' index.md ';'
27+
.PHONY: clean
28+
clean:
29+
rm -rf $(BUILDDIR)/*
30+
rm -rf $(SOURCE_DIR)/*
31+
32+
.PHONY: preview
33+
preview: setup
34+
cd .. && ./docs/_utils/doxygen.sh
35+
poetry run sphinx-autobuild -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml --port 5500
36+
37+
.PHONY: dirhtml
38+
dirhtml: setup
39+
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
40+
@echo
41+
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
42+
43+
.PHONY: singlehtml
44+
singlehtml: setup
45+
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
46+
@echo
47+
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
48+
49+
.PHONY: epub
50+
epub: setup
51+
$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
52+
@echo
53+
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
54+
55+
.PHONY: epub3
56+
epub3: setup
57+
$(SPHINXBUILD) -b epub3 $(ALLSPHINXOPTS) $(BUILDDIR)/epub3
58+
@echo
59+
@echo "Build finished. The epub3 file is in $(BUILDDIR)/epub3."
60+
61+
.PHONY: dummy
62+
dummy: setup
63+
$(SPHINXBUILD) -b dummy $(ALLSPHINXOPTS) $(BUILDDIR)/dummy
64+
@echo
65+
@echo "Build finished. Dummy builder generates no files."
66+
67+
.PHONY: linkcheck
68+
linkcheck: setup
69+
$(SPHINXBUILD) -b linkcheck $(SOURCE_DIR) $(BUILDDIR)/linkcheck
70+
71+
.PHONY: multiversion
72+
multiversion: setup
73+
poetry run ./_utils/multiversion.sh
74+
@echo
75+
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
76+

‎docs/_utils/deploy.sh

+15
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
#!/bin/bash
2+
3+
# Clone repo
4+
git clone "https://x-access-token:${GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}.git" --branch gh-pages --single-branch gh-pages
5+
cp -r docs/_build/dirhtml/* gh-pages
6+
# Redirections
7+
./docs/_utils/redirect.sh > gh-pages/index.html
8+
# Deploy
9+
cd gh-pages
10+
touch .nojekyll
11+
git config --local user.email "[email protected]"
12+
git config --local user.name "GitHub Action"
13+
git add .
14+
git commit -m "Publish docs" || true
15+
git push origin gh-pages --force

‎docs/_utils/doxygen.sh

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
#!/bin/bash
2+
3+
OUTPUT_DIR="docs/_build/dirhtml/api"
4+
if [[ "$SPHINX_MULTIVERSION_OUTPUTDIR" != "" ]]; then
5+
OUTPUT_DIR="$SPHINX_MULTIVERSION_OUTPUTDIR/api"
6+
echo "HTML_OUTPUT = $OUTPUT_DIR" >> doxyfile
7+
fi
8+
mkdir -p "$OUTPUT_DIR"
9+
doxygen doxyfile

‎docs/_utils/multiversion.sh

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
#! /bin/bash
2+
3+
cd .. && sphinx-multiversion docs/source docs/_build/dirhtml \
4+
--pre-build './docs/_utils/doxygen.sh' \
5+
--pre-build "find docs/source -name README.md -execdir mv '{}' index.md ';'"

‎docs/_utils/redirect.sh

+13
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
#!/bin/bash
2+
3+
cat <<- _EOF_
4+
<!DOCTYPE html>
5+
<html>
6+
<head>
7+
<title>Redirecting to Driver</title>
8+
<meta charset="utf-8">
9+
<meta http-equiv="refresh" content="0; URL=./${LATEST_VERSION}/index.html">
10+
<link rel="canonical" href="./${LATEST_VERSION}/index.html">
11+
</head>
12+
</html>
13+
_EOF_

‎docs/_utils/redirections.yaml

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
api: /api/classes.html

‎docs/_utils/setup.sh

+16
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
#! /bin/bash
2+
3+
if pwd | egrep -q '\s'; then
4+
echo "Working directory name contains one or more spaces."
5+
exit 1
6+
fi
7+
8+
which python3 || { echo "Failed to find python3. Try installing Python for your operative system: https://www.python.org/downloads/" && exit 1; }
9+
# install pipx
10+
which pipx || python3 -m pip install --user pipx
11+
python3 -m pipx ensurepath
12+
13+
# install poetry
14+
which poetry || pipx install poetry
15+
poetry --version || { echo "Failed to find or install poetry. Try installing it manually: https://python-poetry.org/docs/#installation" && exit 1; }
16+
poetry install

0 commit comments

Comments
 (0)