Quickstart¶

Prerequisites¶

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.10 or 3.12.

• Poetry 1.8.1.

• Make.

• Git.

Step 1: Create a new doc¶

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.

Step 2: Add the page to the toc tree¶

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:

1. Look in the folder you have created the page and find the index.rst file which is inside the same directory.

2. Edit the toctree directive to include the name of the new topic without its extension. For example:

   .. toctree::
      :maxdepth: 2
   
      my-new-page
   

3. Save the file.

Step 3: Preview the docs locally¶

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:

1. From the command line, run make preview within the docs folder:

   cd docs
   make preview
   

   Tip

   For troubleshooting, refer to the preview command documentation.

2. 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.

Next steps¶

Do you want to submit your changes? See our Docs contributor’s handbook.