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.
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 email@example.com:codinggrace/coding-grace-guide.git > git branch -M main
Now that's all set up, I just pushed my files to github.
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'
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
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.
- 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.
This solution helped. Just looked in the conf.py and commented out
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!