Was this page helpful?
Caution
You're viewing documentation for a previous version of ScyllaDB Sphinx Theme. Switch to the latest stable version.
This guide will show you how to create your first documentation page, list it in the table of contents, and preview the site locally.
You must have a project cloned locally with the documentation toolchain. Additionally, you will need to have installed:
A Unix-based terminal. For Windows, use Windows Subsystem for Linux.
Python 3.9 or later.
Poetry 1.5 or later.
Make.
Git.
Under the docs folder (docs/source in some projects), create a new .rst file.
For example, we named our file my-new-page.rst and added the following content:
=============
My first page
=============
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas id risus laoreet libero bibendum pharetra non ut sem. Curabitur in nulla diam.
Donec scelerisque neque lectus, et fringilla eros vestibulum vel. Suspendisse vitae dolor volutpat, lobortis libero a, commodo mi.
Aenean pretium neque sit amet erat vulputate laoreet. Mauris dapibus vel dui sit amet bibendum.
Tip
If you are not familiar with restructuredText syntax, refer to Examples.
When creating new pages, you must add the topic to the toc tree. If you do not you will have an error when compiling.
To add the page to the toc tree:
Look in the folder you have created the page and find the index.rst file which is inside the same directory.
Edit the toctree directive to include the name of the new topic without its extension. For example:
.. toctree:: :maxdepth: 2 my-new-page
Save the file.
Included in every existing documentation project is a make file. This file contains scripts that you can run to create a testing environment, compile the docs, and produce a local sandbox (website) to test the rendering of the HTML documentation.
To preview the docs locally:
From the command line, run make preview within the docs folder.
Open http://127.0.0.1:5500/ to preview the generated site with you changes.
From the Make file (located in most projects in the /docs/makefile directory), there are more scripts you can run. For more information, see Commands.
Do you want to submit your changes? See our Docs contributor’s handbook.
Was this page helpful?