Allow using Bootstrap3 panels instead of alerts for admonitions

[althonos]

Hi there!

I've been using your Sphinx theme ever since sphinxjp.themes.basicstrap started breaking, and I've never regretted it, it now powers https://instalooter.readthedocs.io/en/latest/ and I'm very happy with the result.

I tend to use a lot of admonitions in my docstrings (mostly because Napoleon with Google docstrings make them feel quite natural), but one thing I never really liked was that the rendered alerts were making any special text hard to read (for instance with the flatly theme):

However, using panels instead of alerts really helps with legibility while still feeling like a coherent section:

I added the admonition_use_panel option to the theme configuration that must be manually set to True to enable the new behaviour (therefore this change is backwards compatible). I also reduced the padding a bit from the default to give the panels a more compact look, so that they take around the same space as the original alerts (title aside).

[althonos]

ping @ryan-roemer just in case

[ryan-roemer]

Hi! I’m on parental leave for this period going until the end of October. Once I’m back I will try and turn to this. One blocker which I recently encountered is that I am now many years away from normal python development and publishing to PyPi doesn’t seem to work with my old stack anymore. I will probably file a generic help wanted issue soon but if you have any insight into modern publishing given the nuances of how things work with the current publish Scripts that would be super useful additional help/PR!

[althonos]

@ryan-roemer : Congratulations ! No problem, take your time, I just pinged you in case you didn't see the issue. I could probably help setup automated deployment from Travis-CI or any other CI if you want help on that; that's what I use for all my projects, where I just need to git tag a release for it to be uploaded on PyPI after it passes a test harness. Don't hesitate to @ me if you'd like me to setup something similar.

[ryan-roemer]

Hi @althonos -- I'm getting back into action in the coming weeks. The thing I'm stuck with is this bespoke .rst->.txt conversion as part of my sdist is all broken on modern Python. Separately, I'm unable to just publish to Python with existing libraries. If you or someone could modernize just the publishing tooling to actually work with modern Python in a separate PR that would be huge!

[svenevs]

@althonos please share thoughts on tooling in #202 🙂