"Fun" fixing problems with my Coding Grace Guide in Sphinx and ReadTheDocs

So, it's been 3 years since I build my Coding Grace Guide docs. Besides the builds failing, why do I want to go through the trouble of fixing it and why it's failing?

Well, it doesn't help that Atlassian sunsetted Mercurial support on Bitbucket (they deleted all repos on everyone!). 😢 I did move what I needed off that and migrated to Github, but I forgot about my guide, which thankfully I had locally on my machine.

Moved Coding Grace repos from BitBucket to GitHub

whykay 👩🏻‍💻🐈🏳️‍🌈 (she/her) for Coding Grace Foundation ・ Jun 23 '20

#diversityintech #learning #news #github

Why?

I've gotten a few emails that the source code was still pointing to bitbucket and the folks following the workshop would like to get access to the code. Therefore I wanted to update the docs because... why not? 🙃

• Building on Sphinx: Make sure you are in the right environment, I'm using pyenv. As I'm on a new machine, I installed Sphinx (so it's definitely the latest version)

exception: No module named 'sphinx.ext.pngmath

Oh boo, where did this come from? Well, this apparently "pngmath module was removed since 1.8. The successor is sphinx.ext.imgmath".

Oh lovely, I'm using the latest version, so "why dis?"

Hmm, I know, let's just start with a new sphinx build environment with sphinx-quickstart and copied over the files I needed and kicked off a build locally with sphinx-build -b html . build.

Ok, that worked!

So ignoring the build directory that was created automatically, ran git init to create a git repos.

Headed over to github and created new repos there and followed the instructions on pushing an existing repo locally on the machine to it.

> git remote add origin [e-mail]:codinggrace/coding-grace-guide.git
> git branch -M main

Now that's all set up, I just pushed my files to github.

codinggrace / coding-grace-guide

STEP 1
======
If you don't have sphinx installed, if you have 'pip', just run 'pip install sphinx'.

You can check out http://sphinx-doc.org/ for more information.


STEP 2
======
sphinx-build -b html . build


STEP 3
======
Open up browser and load 'build/index.html'

View on GitHub

Here a couple of solutions I found online:-

• update Sphinx (for me, it's already the latest version)
• I'm lucky my docs structure is quite straight forward and not that big, I didn't initially tried to export my hg repo into git. I tried using fast-export, and after jumping through hoops it didn't export anything. So I decided to ignore this 3rd party app and just copy the files I need to a new directory and just create a new git repo from that.

Oh well, c'est la vie, I suppose. Not all solutions from internetz work all the time.

Off to Read the Docs

In "Admin"

• Changed Repository URL: to point to my github repo
• Changed Repository type: to Git Saved the changes, and head over to Builds and clicked the Build Version to kick off the build.

And if fell over on the sphinx.ext.imgmath error again!?!

How did I fix it? Did a search with that error and included readthedocs in the search terms.
Double-checked my conf.py file... oh crumbs, I forgot to copy it over from my original hg repo to my git repo. Did that, added, committed and pushed changes. Kicked off the ReadTheDocs build again.

Still broken!

This solution helped. Just looked in the conf.py and commented out 'sphinx.ext.pngmath',.

Committed the changes and pushed it back to github repo.

You guessed it, click on Build Version again in Builds on ReadTheDocs.

And it worked!

Double-checked the latest docs are updated via https://coding-grace-guide.readthedocs.io/en/latest/

So there you go, few hours well spent. I just need to update the docs now that I can generate docs again!