AI PR creation: Fixing the docs build with the help of AI

This is a narrative that shows how I used AI to identify why spin docs fails because of the warning message:

WARNING: the pydata_sphinx_theme extension is not safe for parallel writing
WARNING: doing serial write

Intro

I've never used sphinx nor spin. I've only used makefiles to run a make command following instructions for fixing an issue on my Ubuntu machine. Everything here is brand new.

I have access to GPT-4o and used it for all my discussions related to NumPy's PR 26478.

First Conversation

My first prompt was

WARNING: the pydata_sphinx_theme extension is not safe for parallel writing.

I didn't ask a question, rather just pasted the warning. This told me the parameter -j was the issue, and that I need to use -j 1 somewhere. Where?

Second conversation

My second prompt was

When building a makefile with sphinx, it keeps adding "-j auto" at the end of my configuration files.  Is this a setting in sphinx that I can change? If so, how?

I learned to look for SPHINXOPTS (cmds.py, some makefiles, and .circleci/config.yml). GPT said to remove -j auto, but it wasn't listed and searching the entire codebase for -j auto found lines with spin test -j auto, nothing doc related. GPT also suggested something like using SPHINXOPTS = "" from the command line, which didn't work. I also found a similar comment in the documentation in cmds.py telling me the same suggestion, with no success.

My next prompt was

Currently there is a line in the makefile that looks like this

ALLSPHINXOPTS   = -WT --keep-going -d build/doctrees $(PAPEROPT_$(PAPER)) \
                  $(SPHINXOPTS) source

This prompt was enough to show me to put -j 1 at the end of the ALLSPHINXOPTS definition. It worked. The docs built without warnings. But this looked like a terrible place to put the -j 1, because the generated build command (below) with this change still had the -j auto in it.

LANG=C sphinx-build -b html -WT --keep-going -d build/doctrees  -j auto source build/html -j 1

At least the docs were building, but putting a -j 1 manually at the end looked horrible.

Third conversation

I asked GPT (horrible grammar)

Where in this file are is SPHINXOPTS set

and then copy/pasted the entire makefile.

I learned what ?= means.
I moved -W from ALLSPHINXOPTS to SPHINXOPTS and then ran SPHINXOPTS = "" spin docs which fully generated the docs with warnings and no errors. The current -W needed to be moved so that the user can override it.

I also found out at this point that using make with SPHINXOPTS = "-j 1" worked fine, but not when using spin docs. The two follow a slightly different process. I asked GTP:

Ok, sounds good.  I'm running the make file with the command

SPHINXOPTS="--jobs 1" spin docs

but then during the process I see the following line appears

LANG=C sphinx-build -b html -WT --keep-going -d build/doctrees  --jobs 1 -j auto -j 1 source build/html 

The only thing I don't understand is how "-j auto" is being inserted into the line.

The result wasn't great, but it did suggest some preset value for --jobs. My next prompt:

The only files in the code base that include "-j auto" appears in the context of "spin test" which runs the test, not build the docs.  Here is where the "-j" job is defined, with a default parameter of "auto".  How would this impact the workflow?

<inserted entire contents of `def docs` along with `@click.` stuff above it. I had no idea what @click was.>

Here I finally got the correct placement of -j in spin docs -j 1. The build worked and the -j auto was correctly replaced by -j 1. I swapped the default in

@click.option(
    '--jobs', '-j',
    metavar='N_JOBS',
    default="auto",
    help="Number of parallel build jobs"
)

to default = "1", and I was able to type spin docs and build the documentation.

After playing around with the options, setting the default jobs to various values, and moving the -W around, I was satisfied with the fix. I spent several hours learning what all the commands above do. I waited a day, agonized over what a PR should look like, second guessed everything. I wanted a cleaner version that didn't insert -j 1 into the build command AFTER SPHINXOPTS (making it impossible to override -j), but didn't find a way.

Wrap up

I eventually submitted a PR late Saturday night after agonizing over what it should look like for way too long. Writing the commit message, and the initial comment took probably twice as long as discovering and fixing the issue. I woke up the next day after having a nightmare about my PR. Haha.... It's definitely an emotional journey.

Monday came, and someone else in the world (@eagunn - thank you for commenting) mentioned they too had spent several hours spread over multiple days, trying to get the build to work. A few hours later, it was merged into the code base.

possee-org / genai-numpy