Look into alternatives to Sphinx

[james-westwood]

Sphinx has proven to be a bit difficult. We have it working, so we do not need to ditch it, but if there are nicer alternatives then we might want to look into how easy/difficult it would be to move over to them.

Alternatives I am aware of:

• mkdocs
• Jupyter Book

[jwestw]

I have started work on this. I think that mkdocs looks like the way to go, since we need automatic documentation of the code (via the docstrings) and we are starting with .md files.

[jwestw]

This has gone really well. mkdocs is really easy compared to Sphinx. I had no trouble at all creating all the documentation using mkdocs. Check the branch for code updates. Here's a screenshot of the output using the same theme as we were in Sphinx

Note: this is locally hosted at the moment, but I have made tickets to host on gh-pages

[jwestw]

I was able to rebuild the pages and host locally. The github runner to rebuild and deploy seems to be working (as in it is reporting no errors) but it is not showing the new pages on the website. Checked the gh-pages branch and it seems to all be correct.

[jwestw]

Great! We now have a web page with all our documentation which was built by mkdocs. It was much easier to do this that with Sphinx (sorry Sphinx).

Still left to do (will create other issues):

• https://github.com/ONSdigital/SDG_11.2.1/issues/409
• https://github.com/ONSdigital/SDG_11.2.1/issues/405
• https://github.com/ONSdigital/SDG_11.2.1/issues/411

[james-westwood]

This is done.