Skip to content

Latest commit

 

History

History
95 lines (56 loc) · 3.1 KB

CONTRIBUTING.rst

File metadata and controls

95 lines (56 loc) · 3.1 KB
Raw

Contribute

Thank you for your help improving sphinx-icon!

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

  • mypy: to perform a mypy check on the lib;
  • 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 sphinx-icon codebase. You can clone it for local development like so:

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 }}/icon
cd icon

Then install the development version of the extension:

pip install -e .[dev]

This will install the sphinx-icon 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 :ref:`below <contributing-docs>` for more information on how to update the documentation.

Contribute to the docs

The documentation is built using Sphinx and deployed to Read the Docs.

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.