docs: add sample site

[dgarcia360]

Closes #125

Motivation

Adds a sample docs site to the project.

How to test

1. Make sure you meet the prerequisites.
2. Clone the PR.
3. Go to the docs folder: cd docs
4. Build the docs: make preview
5. The site should render at http://127.0.0.1:5500/

Next steps after merging

1. Add content to the site (maintainers)
2. Request zendesk tag for this project, optional (@annastuchlik)
3. Request subdomain to IT (@annastuchlik)
4. Configure GitHub Pages (maintainers)

Could you please enable the following option?

In the repository’s Settings, navigate to the Pages section and select GitHub Actions as the deployment source.

Thanks!

[muzarski]

Sorry, for the huge delay.

I tried to build it locally. Here are the results:

$ make preview
poetry install
Installing dependencies from lock file

Package operations: 0 installs, 23 updates, 0 removals

  - Downgrading certifi (2024.8.30 -> 2024.6.2)
  - Downgrading idna (3.10 -> 3.7)
  - Downgrading markupsafe (3.0.0 -> 2.1.5)
  - Downgrading urllib3 (2.2.3 -> 2.2.2)
  - Downgrading babel (2.16.0 -> 2.15.0)
  - Downgrading sphinxcontrib-applehelp (2.0.0 -> 1.0.8)
  - Downgrading sphinxcontrib-devhelp (2.0.0 -> 1.0.6)
  - Downgrading sphinxcontrib-htmlhelp (2.1.0 -> 2.0.5)
  - Downgrading sphinxcontrib-qthelp (2.0.0 -> 1.0.7)
  - Downgrading sphinxcontrib-serializinghtml (2.0.0 -> 1.1.10)
  - Downgrading anyio (4.6.0 -> 4.4.0)
  - Downgrading rich (13.9.2 -> 13.7.1)
  - Downgrading soupsieve (2.6 -> 2.5)
  - Downgrading zipp (3.20.2 -> 3.19.2)
  - Downgrading mdit-py-plugins (0.4.2 -> 0.4.1)
  - Downgrading pyyaml (6.0.2 -> 6.0.1)
  - Downgrading sphinx-notfound-page (1.0.4 -> 1.0.2)
  - Downgrading starlette (0.39.2 -> 0.37.2)
  - Downgrading typer (0.12.5 -> 0.12.3)
  - Downgrading uvicorn (0.31.0 -> 0.30.1)
  - Downgrading watchfiles (0.24.0 -> 0.22.0)
  - Downgrading websockets (13.1 -> 12.0)
  - Downgrading sphinx-multiversion-scylla (0.3.2 -> 0.3.1)
poetry update
Updating dependencies
Resolving dependencies... (0.7s)

Package operations: 0 installs, 23 updates, 0 removals

  - Updating certifi (2024.6.2 -> 2024.8.30)
  - Updating idna (3.7 -> 3.10)
  - Updating markupsafe (2.1.5 -> 3.0.0)
  - Updating urllib3 (2.2.2 -> 2.2.3)
  - Updating babel (2.15.0 -> 2.16.0)
  - Updating sphinxcontrib-applehelp (1.0.8 -> 2.0.0)
  - Updating sphinxcontrib-devhelp (1.0.6 -> 2.0.0)
  - Updating sphinxcontrib-htmlhelp (2.0.5 -> 2.1.0)
  - Updating sphinxcontrib-qthelp (1.0.7 -> 2.0.0)
  - Updating sphinxcontrib-serializinghtml (1.1.10 -> 2.0.0)
  - Updating anyio (4.4.0 -> 4.6.0)
  - Updating rich (13.7.1 -> 13.9.2)
  - Updating soupsieve (2.5 -> 2.6)
  - Updating zipp (3.19.2 -> 3.20.2)
  - Updating mdit-py-plugins (0.4.1 -> 0.4.2)
  - Updating pyyaml (6.0.1 -> 6.0.2)
  - Updating sphinx-notfound-page (1.0.2 -> 1.0.4)
  - Updating starlette (0.37.2 -> 0.39.2)
  - Updating typer (0.12.3 -> 0.12.5)
  - Updating uvicorn (0.30.1 -> 0.31.0)
  - Updating watchfiles (0.22.0 -> 0.24.0)
  - Updating websockets (12.0 -> 13.1)
  - Updating sphinx-multiversion-scylla (0.3.1 -> 0.3.2)

Writing lock file
poetry run sphinx-autobuild -b dirhtml -d _build/doctrees  -j auto source _build/dirhtml --port 5500
[sphinx-autobuild] Starting initial build
[sphinx-autobuild] > sphinx-build -b dirhtml -d _build/doctrees -j auto source _build/dirhtml
Running Sphinx v7.3.7

Extension error:
Could not import extension sphinx_multiversion (exception: No module named 'distutils')
Sphinx exited with exit code: 2
The server will continue serving the build folder, but the contents being served are no longer in sync with the documentation sources. Please fix the cause of the error above or press Ctrl+C to stop the server.
[sphinx-autobuild] Serving on http://127.0.0.1:5500
[sphinx-autobuild] Waiting to detect changes...
^C

Some context:

python --version
Python 3.10.15

poetry --version
Poetry (version 1.8.1)

I'm not sure how to resolve this issue. I tried installing/uninstalling some packages but nothing worked.

[annastuchlik]

I'll defer to @dgarcia360.

[muzarski]

Ok, it seems that I had to do a separate poetry installation for python 3.10 (previous installation was for system python version - 3.12).

BTW, prerequisites mention that python 3.12 should work, but it does not seem to be the case. I needed to downgrade to python 3.10.

The docs page is rendered as expected:

There are some conflicts to be resolved. Also, I saw this PR, where we update sphinx scyllaDB theme to 1.8 for rust driver. I think this needs to be addressed here as well. Apart from that, LGTM.

[muzarski]

Could you please enable the following option?

In the repository’s Settings, navigate to the Pages section and select GitHub Actions as the deployment source.

Thanks!

FYI, it's enabled

[dgarcia360]

Thanks to @muzarski for reviewing.

The theme is compatible with Python 3.12 starting from Sphinx Theme version 1.7.1.

I'll update the theme to the latest version before merging.

[dgarcia360]

Sorry for the delay, docs theme updated to the latest version

[muzarski]

LGTM. Made a preview locally and it works as expected.

The failure in CI does not seem to depend on the changes introduced by this PR. I'll investigate it later.