Sphinx Site Log#

12/08/2024#

Running the Sphinx quickstart command#

When researching the documentation online, I found that Sphinx comes with a command to quickly setup our project folder.[1]

I noticed that the command by default asks you some prompts in the setup process. I found this a bit clunky. And because I originally was going to include this section in the main tutorial, I wanted to know if I could instead somehow specify flags to disable this functionality to make it more seamless. I then found that this was indeed possible.[2]

I then ran the modified command which included the new flags in the project folder:

sphinx-quickstart -q --sep -p=PROJECT -a=AUTHOR

To explain the flags:

  • -q skips the interactive prompts.

  • --sep better organises the project by creating separate source and build folders.

  • -p and -a are required flags when using -q, and are used to set the project name and author variables in the generated conf.py file.

Running the command created a bunch of files and folders that looked like this:

build/
source/
├── _static
├── _template
├── conf.py
└── index.rst
make.bat
Makefile

Deleting unnecessary files#

I noticed that the _static/ and _template/ folders were empty, so I deleted them to reduce the clutter as I wanted to provide anyone who used this template as clean of a setup as possible. I also deleted the default index.rst since I wanted to use .md files over .rst, and keeping .rst around seemed unintuitive. The folder now looked like this:

build/
source/
└── conf.py
make.bat
Makefile

To explain the current state of the folder:

  • source/ will contain all the .md and .ipynb files we wish to upload to our website.

  • make.bat and Makefile will be used to convert the files in source/ into web pages.

  • build/ is where the converted files (now written in HTML etc.) are stored.

  • source/conf.py is where we can configure the Sphinx site (e.g. set a theme).

Adding extensions#

Earlier I installed a bunch of Sphinx extensions in my Dockerfile. We can now finally enable them on the site through the conf.py file.

Inside the file, you will find the line: extensions = []. To add our extensions, I edited the line to the following:

extensions = ["myst_nb", "sphinx_design", "sphinx_copybutton"]

  • myst-nb: Makes .md and .ipynb files compatible with Sphinx.

  • sphinx-design: Allows the creation of more complex web components such as cards.

  • sphinx-copybutton: Adds a copy button to code snippets that website viewers can use to easily copy code.

Setting the theme#

Inside the same conf.py file, I set the theme by locating the line: html_theme = 'alabaster' and editing it to the following:

html_theme = "pydata_sphinx_theme"

The Sphinx site has now been configured with its theme and all necessary extensions.

07/09/2024#

Inconsistencies in local preview#

When adding buttons to my site, I omit the .html as the live site does not include it in URLs, however, when I view the website locally, I would need to add the .html, otherwise the file of course is not present on my computer.

There are also other funny issues with Sphinx. For instance, if you edit a page title which is in a section, you will find that when navigating to other pages in the same section, the page title remains old.

Discovering the sphinx-autobuild extension#

When browsing broadly online for helpful Sphinx extensions[3], I came across sphinx-autobuild.

Much like how React works, it creates a local server which mimics a live one. Because of this, I would no longer need to edit the URL just to find the correct file.

Additionally, it fixed the second problem. The primary feature of this extension was that it would detect changes and update the preview live - even those which indirectly altered other pages.

I first installed the sphinx-autobuild package by editing my Dockerfile. I should note that I didn’t need to add the extension to my site for it to work.

Then to make it actually work, you need to run the following command:

sphinx-autobuild -a -b dirhtml source build

  • -a: Detect changes which indirectly alter pages.

  • -b dirhtml: Removes the .html postfix from URLs.

  • source build: Specifies source and build folder names.

Running sphinx-autobuild automatically#

To go further, I added the above command to the postStartCommand field in the devcontainer.json file. This means that whenever the project is ran, the local server is automatically launched without any command from the user.

And with that, one more problem had been fixed.