Move sphinx-click into pallets ecosytem from click-contrib. Rehome click-example, click-run (click-extra) into click-sphinx

[Rowlando13]

It would be nice be able to use click-example and click-run in our docs in Myst. @kdeldycke Already has the work done, but its in click-extra. I think it would make sense to move sphinx-click to pallets ecosystem, then move the work the directives to that package. It only has sphinx click stuff in it. Then click can depend on it for its doc's generation without impinging on click-extra's ability to move more quickly. I will do the legwork to make it happen. What are your thoughts about whether it is a good idea or not? @kdeldycke @davidism

[kdeldycke]

I don't mind contributing back/relicensing my work on Sphinx from Click Extra to Pallets proper. Don't expect drama on this side to me. I'm happy for my code to be promoted! 😉 If the community identifies some parts you want to reuse, go ahead and feel free to copy and paste. As long as I have the freedom to be a bit aggressive and creative with Click Extra, I'm happy! :)

Sphinx internals can be a bit dense and intimidating, and Click needs some tricks to simulate CLI execution and trace (on the 3 main platforms). So for me it makes sense to concentrate all code interfacing the two worlds in a single project. That was my initial proposition in:

• Move .. click:example:: and .. click:run:: implementation to sphinx-click pallets-sphinx-themes#61
• Supports .. click:example:: and .. click:run:: directives click-contrib/sphinx-click#110

In the mean time, and for context, my Sphinx ↔ Click work is available at:

• https://kdeldycke.github.io/click-extra/sphinx.html
• https://github.com/kdeldycke/click-extra/blob/main/click_extra/sphinx.py
• https://github.com/kdeldycke/click-extra/blob/main/tests/test_sphinx.py

[Rowlando13]

Sounds good. @davidism Assuming that I get sphinx-click moved into pallets eco and cut a release with the new functionality, would you feel comfortable deprecating the functionality in pallets-sphinx-theme ?

[Rowlando13]

@kdeldycke I left an issue in sphinx-click but never got an answer. So I think moving any functionality there is probably a no go. I chatted with @davidism at Pycon, and the long term plan is for pallets-sphinx-theme to go away and for pallets to move to a more broadly used theme, probably furo. To help I am going to move the click::example and 'click:run` to a separate repo click-autodoc that will get moved into pallets eco. I will vendor your sphinx roles code and hopefully cut a release sometime soon!

[davidism]

Maybe sphinx-click-block or click-sphinx-block is a better name for it? "autodoc" suggests it will be similar to sphinx's own autodoc extension, and I'm not sure what that might look like.

[kdeldycke]

@kdeldycke I left an issue in sphinx-click but never got an answer. So I think moving any functionality there is probably a no go.

You mean this one: click-contrib/sphinx-click#158 ? Yeah, I'm not surprised as my implementation in Click Extra is kind of maximalist. And I still have some niche features to add. Merging all of that into sphinx-click might be invasive. I totally understand @stephenfin answer at click-contrib/sphinx-click#158 (comment) .

I chatted with @davidism at Pycon, and the long term plan is for pallets-sphinx-theme to go away and for pallets to move to a more broadly used theme, probably furo.

That's also a good call. I ended up adopting Furo too in all my Sphinx projects. Maintaining my own theme is too much work and distracting. I prefer to focus on the content of my doc than their design.

To help I am going to move the click::example and 'click:run` to a separate repo click-autodoc that will get moved into pallets eco. I will vendor your sphinx roles code and hopefully cut a release sometime soon!

As @davidism pointed out, click-autodoc might be an unfortunate name given Sphinx's own autodoc vocabulary. Unless you are going to extend the autodoc machinery itself.

And feel free to vendor/copy/get inspiration from Click Extra. Don't forget to link to my project so people can trace back the origins and resync the code if you vendor it in.

[stephenfin]

I missed this discussion previously (thanks for the tag, @kdeldycke) but as I discussed with Kevin way back, sphinx-click has a small, well defined use case that mostly just works and I don't really want to expand upon this. I'd much rather additional functionality be kept in a separate package as it currently is with click-extra. Hopefully that makes sense, but you're naturally free to fork it if you disagree.