Posts tagged sphinx

A Sphinx directive for social media embeds

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.

Read more ...

Bundle extensions with your Sphinx theme

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.

Read more ...

How to update Sphinx options during the build

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 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.

Read more ...

Custom roles and domains in Sphinx with one line

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:

Read more ...

A new blog with Sphinx

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 ;-)

Read more ...

Using CircleCI to preview documentation in Pull Requests

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.

Read more ...

Adding copy buttons to code blocks in Sphinx

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:

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.

Read more ...