This quickstart walks you through the steps required to add the documentation toolchain to a ScyllaDB project hosted on GitHub.
Before adding the documentation toolchain to a project, you will need to have installed Python +3.7 and PIP on your local environment.
If you are on Windows, you will need to run
make commands from a Unix-based terminal such as Git Bash.
.github directories from the repository scylladb/sphinx-scylladb-theme to the root directory of the project where you want to set up docs. The project’s directory structure should look like the following:
project-name/ ├── .github/ | ├── workflows/ | | ├── docs-pages@vX.yaml | | ├── docs-pr@vX.yaml ├── docs/ │ ├── _utils/ │ | ├── redirections.yaml │ | ├── deploy.sh │ | ├── setup.sh │ ├── source/ │ ├── Makefile
If you already have docs in the project under an existing
docs directory, move the doc files to
Create the file
docs/pyproject.toml under the new
docs folder. Copy the contents from the pyproject.toml template.
Edit the file
docs/source/conf.py file to suit the project needs (e.g., edit the project name and site description, install new extensions, …).
For more information, see Configuration.
If you don’t already have a
.gitignore file in the project, place one in the root directory and include
/source/.doctrees in it.
If you already have a
.gitignore file, add both paths to the file.
Delete or adapt the sample documentation files under
From the command line, run
make preview within the
docs folder. Fix any warnings raised by Sphinx.
Once the docs build without errors, open
http://127.0.0.1:5500/ to preview the generated site.