Skip to main content
`Ctrl`+`K`

# Contribute

Thank you for your help improving sphinxcontrib-youtube!

sphinxcontrib-youtube uses nox to automate several development-related tasks. Currently, the project uses four automation processes (called sessions) in `noxfile.py`:

- `test`: to run the test with pytest;

- `docs`: to build the documentation in the `build` folder;

- `lint`: to run the pre-commits in an isolated environment

Every nox session is run in its own virtual environment, and the dependencies are installed automatically.

To run a specific nox automation process, use the following command:

    nox -s <session name>

For example: `nox -s test` or `nox -s docs`.

## Workflow for contributing changes

We follow a typical GitHub workflow of:

- Create a personal fork of this repo

- Create a branch

- Open a pull request

- Fix findings of various linters and checks

- Work through code review

See the following sections for more details.

## Clone the repository

First off, you’ll need your own copy of the sphinxcontrib-youtube codebase.

Fork the repository so you have your own copy on GitHub. See the GitHub forking guide for more information.

Then, clone the repository locally so that you have a local copy to work on:

    git clone https://github.com/<YOUR USERNAME>/youtube
    cd youtube

Then install the development version of the extension:

    pip install -e .[dev]

This will install the sphinxcontrib-youtube library, together with two additional tools:

- pre-commit for automatically enforcing code standards and quality checks before commits.

- nox, for automating common development tasks.

Lastly, activate the pre-commit hooks by running:

    pre-commit install

This will install the necessary dependencies to run pre-commit every time you make a commit with Git.

## Contribute to the codebase

Any larger updates to the codebase should include tests and documentation. The tests are located in the `tests` folder, and the documentation is located in the `docs` folder.

To run the tests locally, use the following command:

    nox -s test

See below for more information on how to update the documentation.

## Contribute to the docs

<https://www.sphinx-doc.org/en/master/>`__ and deployed to Read the Docs The documentation is built using `Sphinx.

To build the documentation locally, use the following command:

    nox -s docs

For each pull request, the documentation is built and deployed to make it easier to review the changes in the PR. To access the docs build from a PR, click on the “Read the Docs” preview in the CI/CD jobs.