"Fun" fixing problems with my Coding Grace Guide in Sphinx and ReadTheDocs
Tags: codinggrace, documentation, sphinx, readthedocs
Published: 2020-10-10 15:53:13

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?

![Screenshot 2020-10-10 at 15.55.46](https://dev-to-uploads.s3.amazonaws.com/i/n5e35a0uep2jo1e1inwx.png)

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.

{% link https://dev.to/codinggrace/moved-coding-grace-repos-from-bitbucket-to-github-5epk %}

# 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](https://github.com/pyenv/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". 

<img src="https://media.giphy.com/media/ZanWL0MNtv3y0/giphy.gif">

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

<img src="https://media.giphy.com/media/pa37AAGzKXoek/giphy.gif">

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 git@github.com:codinggrace/coding-grace-guide.git
> git branch -M main
```
Now that's all set up, I just pushed my files to github.

{% github codinggrace/coding-grace-guide %}

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](https://git-scm.com/book/en/v2/Git-and-Other-Systems-Migrating-to-Git)**, 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.

<img src="https://media.giphy.com/media/12RiLsgUKI4OhW/giphy.gif">

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!?!

<img src="https://media.giphy.com/media/oWzD87unXVd3a/giphy.gif">

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!

<img src="https://media.giphy.com/media/uprwwjptZW4Za/giphy.gif">

This [solution](https://github.com/readthedocs/readthedocs.org/issues/2418#issuecomment-432506602) 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.

![Screenshot 2020-10-10 at 16.48.54](https://dev-to-uploads.s3.amazonaws.com/i/n6ukmhjcqj4wsr2vyk81.png)
 
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!

<img src="https://media.giphy.com/media/11sBLVxNs7v6WA/giphy.gif">