Getting started

Here are some example templates provided to help you get started with writing your documentation. You can use these templates to create your own documentation.

Reuse `.rst` files across multiple pages

Here is how you can reuse a reusable block of .rst files across multiple pages:

5 levels of reusing/sharing code
Level	Name	Scope	How to setup
1	`function`	Reuse code in the single file.	See Level 1 tutorial
2	`module`	Reuse code across files.	See Level 2 tutorial
3	`workspace`	Reuse code across project folders.	`package create workspace`
4	`system`	Reuse code across any files in the computer.	`package create system`
5	`public`	Share code as publicly installable package.	`package create public`

Warning

Ensure that the .rst file you are including is not too long. If it is too long, it may be better to split it into multiple files and include them separately.

Refer to a specific section in the documentation

You can use the ref tag to refer to a specific section in the documentation. For example, you can refer to the section below using the :ref: tag as shown here.

Note

Please check the raw .rst file of this page to see the exact use of the :ref: tag.

Embed your code snippets in the documentation

Here is how you can write a block of code in the documentation. You can use the code-block directive to write a block of code in the documentation. For example, you can write a block of code as shown below:

# Create a new environment, without build dependencies (pure Python package)
conda create -n <package_name>-env python=3.13 \
    --file requirements/test.txt \
    --file requirements/conda.txt

# Create a new environment, with build dependencies (non-pure Python package)
conda create -n <package_name>-env python=3.13 \
    --file requirements/test.txt \
    --file requirements/conda.txt \
    --file requirements/build.txt

# Activate the environment
conda activate <package_name>_env

# Install your package locally
# `--no-deps` to NOT install packages again from `requirements.pip.txt`
pip install -e . --no-deps

# Run pytest locally
pytest

# ... run example tutorials

Attach an image to the documentation

Here is how you attach an image to the documentation. The /docs/source/img/scikit-package-logo-text.png example image is provided in the template.

Other useful directives

Here is how you can do menu selection Admin ‣ Settings and display labels for buttons like Privacy level.