Contribute to the Kedro documentation

You are welcome to contribute to the Kedro documentation if you find something incorrect or missing, or have other improvement suggestions.

You can tell us what we should change or make a PR to change it yourself.

Before you contribute any documentation changes, please read the Kedro documentation style guidelines on this wiki.

How do I rebuild the documentation after I make changes to it?

Our documentation is written in Markdown and built from by Sphinx, coordinated by a build script.

If you make changes to the markdown for the Kedro documentation, you can rebuild it within a Unix-like environment (with pandoc installed).

If you are a Windows user, you can still contribute to the documentation, but you cannot rebuild it. This is fine! As long as you have made an effort to verify that your Markdown is rendering correctly, and you have followed our basic guidelines, we will be happy to take your final draft as a pull request and rebuild it for you.

The following instructions are specifically for people working with documentation who may not already have a development setup. If you are comfortable with virtual environments, cloning and branching from a git repo and using make you don't need them and can probably jump to the section called Build the documentation.

Set up to build Kedro documentation

Follow the setup instructions in the developer contributor guide to fork the Kedro repo, create and activate a Python virtual environment and install the dependencies necessary to build the documentation.

Build the documentation

MacOS users can use make commands to build the documentation:

make build-docs

The build will take a few minutes to finish, and a successful result is a set of HTML documentation in docs/build/html, which you can review by navigating to the following file and opening it: docs/build/html/index.html.

Extend Kedro documentation

Add new pages

All Kedro documentation is collated and built from a single index file, index.rst found in the docs/source folder.

If you add extra pages of documentation, you should always include them within index.rst file to include them in the table of contents and let Sphinx know to build them alongside the rest of the documentation.

Move or remove pages

To move or remove a page of documentation, first locate it in the repo, and also locate where it is specified in the index.rst or .rst for the relevant section within the table of contents.

Create a pull request

You need to submit any changes to the documentation via a branch.

Find out more about the process of submitting a PR to the Kedro project.

Help!

There is no shame in breaking the documentation build. Sphinx is incredibly fussy and even a single space in the wrong place will sometimes cause problems. A range of other issues can crop up and block you, whether you're technically experienced or less familiar with working with git, conda and Sphinx.

Ask for help over on GitHub discussions.

Kedro documentation style guide

We follow a lightweight documentation style guide but we understand that writing English is not an exact science. If you have questions, just ask us on Slack or raise an issue here on GitHub.

How to run kedro-sphinx-theme locally

kedro-sphinx-theme is where we have the Sphinx theme for the Kedro ecosystem

This outlines the steps required to run the Kedro-Sphinx-Theme locally on your machine, either with your kedro, kedro-viz or kedro-dataset.

Before launching a development server, you'd need to have Python(>=3.9) installed. We strongly recommend setting up conda to manage your Python versions and virtual environments. You can visit Kedro's guide to installing conda for more information.

Steps

1. Clone the Kedro-Sphinx-Theme Repository First, you need to get the Kedro-Sphinx-Theme directory on your local machine. Navigate to the directory where you have cloned the repository:

cd kedro-sphinx-theme

Get the location of your local repository and copy the output path for later use:

pwd

2. Setup the docs build requirement in your repository Navigate to the directory where you want to run the documentation locally. This can be within your Kedro, Kedro-Viz, or Kedro-Dataset project:

cd path/to/your/kedro/or/kedro-viz/or/kedro-dataset

Ensure your Python environment is active and ready.Then navigate to the package directory

cd package

Install the documentation dependencies

pip install ".[docs]"

Use the path you copied earlier to install the kedro-sphinx-theme package

pip install -e "path/to/kedro-sphinx-theme"

After installing all the requirements, build the documentation from the root of the repository

cd to/your/root

sphinx-build -WETa --keep-going -j auto -D language=en -b html -d docs/build/doctrees docs/source docs/build

3. Start a Local HTTP Server Finally, navigate to the docs/build directory and start a local HTTP server to view the documentation:

Navigate to the docs/build directory

cd docs/build

Start the server

python -m http.server

Once everything is successfully built and run, you can open the documentation development locally through http://localhost:your-port