Posts tagged sphinx
A Sphinx directive for social media embeds
- 15 February 2023
I often want to link to social and other types of web-based media in my Sphinx documentation and blog. Rather than embedding it all in custom HTML code, I decided to write a little wrapper to turn it into a directive.
It’s called {socialpost}, and it works with Twitter, Mastodon, and YouTube links.
Bundle extensions with your Sphinx theme
- 19 January 2023
Sphinx is great because it has a ton of useful extensions that let you grow its functionality. However, a downside of this is that users have to actually learn about those extensions and activate them manually. It’s not hard, but it’s a non-trivial amount of discovery work.
One way to solve this is for themes to bundle extensions on their own. This way they can include functionality via an extension rather than writing custom code on their own.
How to update Sphinx options during the build
- 05 December 2022
As part of the pydata-sphinx-theme we have a few settings that auto-enable extensions and configure them on behalf of the user.
It has always been mysterious to me how to do this properly during the Sphinx build.
It’s easy to configure things with conf.py ahead of time, but what if you want to manually set a value during the build?
I finally figured it out, so documenting the process here.
Custom roles and domains in Sphinx with one line
- 21 November 2022
I was working on the roles and structure section of the 2i2c Team Compass and found a nifty feature in Sphinx that I hadn’t known before.
You can currently add labels to any section with the following MyST Markdown structure:
A new blog with Sphinx
- 10 October 2020
I recently re-wrote all of the infrastructure for my blog so that it now builds on top of the Sphinx ecosystem! This is a short post to describe the reasons for doing so, and a bit about the implementation.
This is a great question. The answer to “should you re-work your blog to use a new SSG” is almost always “no, it’s a waste of your time”, but I think I had a few good reasons ;-)
Using CircleCI to preview documentation in Pull Requests
- 16 October 2018
Writing documentation is important - it’s the first point of contact between many users and your project, and can be a pivotal moment in whether they decide to adopt your tech or become a contributor.
However, it can be a pain to iterate on documentation, as it is often involves a lot of rapid iteration locally, followed by a push to GitHub where you “just trust” that the author has done a good job of writing content, design, etc.
Adding copy buttons to code blocks in Sphinx
- 05 July 2018
NOTE: This is now a sphinx extension! Thanks to some friendly suggestions, I’ve written this up as a super tiny sphinx extension. Check it out here: https://github.com/choldgraf/sphinx-copybutton
Sphinx is a fantastic way to build documentation for your Python package. On the Jupyter project, we use it for almost all of our repositories.