copier-sphinxcontrib

The skeleton of a Sphinx extention ready to be shipped in the sphinxcontrib organisation. It contains:

• pre-commit hooks (prettier, ruff, black)
• nox sessions (doc, pytest, mypy)
• A test structure carefully designed for Sphinx extentions based on the sphinx pytest fixture and pytest-regressions
• a documentation structure based on Sphinx using the pydata-sphinx-theme
• a complete github folder (README, LICENSE, etc...)
• github actions (test, coverage, mypy, lint, release)
• ready to publish on pipy
• ready to document on readthedocs
• ready to report on codecov
• easy contribution using GitHub codespaces.

Demonstration

The package end result is demonstrated in the sphinxcontrib-skeleton repository.

Usage

1. Define an extension name. It can be anything with any normal character (w+) like "Extension Skeleton".

2. Init an empty github repository with the slug name of your extention. A slug should only use lower case characters and replace all spaces with - like "extention-skeleton". To match the name of the package, the repository should be prefixed with "sphinxcontrib-" like "sphinxcontrib-extention-skeleton".

3. Enable the repository on codecov and add a CODECOV_TOKEN github action env variable. With the generated token from codecov.

4. Start a new readthedocs project hooked to the repository. in the admin tick the "build on PR" option.

5. In your local computer start the project by running the following code. Set the same names as in the github repository.

   Note

   You will need to install 2 extra python libs if it's not already done, copier and jinja2-time.

   pip install copier jinja2-time

   copier copy --trust gh:sphinx-contrib/copier-sphinxcontrib sphinxcontrib-<extention-skeleton>

6. Go to the folder and init the git project:

   cd sphinxcontrib-<extention-skeleton>
   git init

7. Run nox tests to see if everything is working. This command will run the 4 nox sessions (lint, tests, mypy, docs)

   nox

8. Install pre-commits:

   pre-commit install

9. Push to distant repository following Github instructions

   git add .
   git commit -m "build: initial commit"
   git remote add origin git@github.com:<username>/sphinxcontrib-<extention-skeleton>.git
   git branch -M main
   git push -u origin main

10. Once you are ready to make a release (or a pre-release to lock the name), Create a new project on pipy by running the first push yourself using version number 0.0.0:

    python -m build
    twine upload dist/**

11. Modify the lib as you see fit

12. Update version with commitizen tools:

    cz bump

13. Add a token to a new github action env variable PYPI_PASSWORD from your pypi profile. limit the scope to this repository only.

14. Start a new release in github and let actions do the rest

15. The generated package will automatically detect new releases of the template and create update PR. follow the instructions in the issue to update your project.