Naming Convention for Packages?

[mmcky]

Maybe missed the boat on this but wanted to open up this discussion on naming conventions for packages.

I was interested to see if others thought a naming convention for packages would be useful -- or if we should just allow them to flourish at the individual level. My engineering brain loves conventions but the open source world typically embraces a bit more organised chaos :-)

What concerns me is there is no indication (for example) that sphinx-book-theme is html only. We had a discussion about this and decided to leave that as is and add sphinx-book-theme.latex for the latex theme (under the premise that html is the default)

We could adopt a convention such as:

jbtheme-book.html for html theme of sphinx-book-theme
jbext- for extensions

One possible point of confusion is that much of what is written for jupyter-book is actually a sphinx theme or extension. So this naming convention may actually confuse things.

sphinxtheme-book for sphinx themes
sphinxext- for sphinx extensions

I think this is low priority and not looking to force this on existing packages but though I'd open this discussion as new packages are being developed.

For sphinx extensions we currently we have a mix of:

1. no identifying name component (i.e. myst_parser)
2. sphinxcontrib-{name} using the sphinxcontrib namespace / organisation approach
3. sphinx-{name} (most common pattern)
4. sphinx-ext-{name} such as sphinx-ext-autodoc

[choldgraf]

Mmm I think that for any pre-existing packages, it would be disruptive to change the name now that they are being used by a lotta folks. It's doable, but I think we'd need to have a really good need for doing so.

I think that the convention I see most generally-applied is: if the package is 100% a Sphinx thing, then call it sphinx-XXX but if not then call it whatever makes the most sense. E.g., sphinx-book-theme, sphinx-thebe, etc. But myst-parser because the parser isn't only a sphinx thing, it can also do non-sphinx functionality as well.

The one exception to this is (I believe) MyST-NB, which is 100% sphinx but doesn't adhere to this name. That said, it may be too late to change that and perhaps there are non-sphinx use-cases in its future?

[mmcky]

thanks @choldgraf I agree I think sphinx- is a good tag for packages that are 100% sphinx.

Does this also means that packages should try and package css etc. to enable them to work in general (rather than just supported for some styling within sphinx-book-theme)?

[choldgraf]

as a general rule that's what I've tried to do w/ CSS, though often include a caveat that the package was designed for a specific theme and may behave more unpredictably for others