Create a template for Sphinx extensions

[choldgraf]

Background

I've found myself often creating new Sphinx extensions from scratch. Each time I do this, there are a bunch of semi-random questions to ask around how to structure setup.py/docs/tox structure/etc. In practice I end up copy/pasting from one of our other extensions and packages.

Options

I think this could be a more streamlined process, and ensure that we have more consistent structure and code in our repositories. A few ways that we could accomplish this if we wished to do so:

• Create a cookiecutter for a Sphinx extension** - I think we'd want this to be relatively simple, rather than a super complex setup. (cookiecutter docs here)
• Create a GitHub repo template - this would let us quickly generate a new github repo from our template. (see the docs here)

Other information

• a cookiecutter for sphinxcontrib exists, but has a lot of patterns specific to the sphinxcontrib community

[chrisjsewell]

Basically, cookiecutter is maybe slightly simpler for the end user, as you don't have to do any find/replacing, and so good e.g. for https://github.com/executablebooks/cookiecutter-jupyter-book, where it makes it nice and simple for the end user. It is also easier to add optional/modal files and/or file content (https://cookiecutter.readthedocs.io/en/latest/advanced/choice_variables.html)

But the big downsides is that they are more of a pain to create/test/maintain, and also you can't inherit any of the additional repo configuration.

For example, I created: https://github.com/executablebooks/python-pkg-cookiecutter, but now I can't be hassled to update it and so I never actually use it, whereas I have recently created (and use):

• https://github.com/executablebooks/mdformat-plugin
• https://github.com/executablebooks/markdown-it-plugin-template

[choldgraf]

@chrisjsewell so you're suggesting using "GitHub Repository Templates" rather than CookieCutter? In that case, we'd recommend somebody follow the GitHub UI in order to create their own version of the template, and go from there?

I think this is a nice balance of quickness without having too much complexity. Certainly as a start this feels like a reasonable choice, and we could explore having a more complex cookiecutter setup if we really thought it was necessary in the future.

[chrisjsewell]

so you're suggesting using "GitHub Repository Templates" rather than CookieCutter?

I think at least initially yeh 👍