Update docs to use custom theme

[ewu63]

Purpose

We created a custom theme which is published on pyPI, to help make all the documentation sites consistent. This accomplishes several things

• Shared theme styles without modifying each repo
• The CSS table fix can be placed in a single place
• Default options for conf.py can be set globally, and imported in each repo without having to change the setting for each repo, e.g. the copyright year

Type of change

What types of change is it?
Select the appropriate type(s) that describe this PR

• Bugfix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (non-backwards-compatible fix or feature)
• Code style update (formatting, renaming)
• Refactoring (no functional changes, no API changes)
• Documentation update
• Maintenance update
• Other (please describe)

Testing

No need

Checklist

Put an x in the boxes that apply.

• I have run flake8 and black to make sure the code adheres to PEP-8 and is consistently formatted
• I have run unit and regression tests which pass locally with my changes
• I have added new tests that prove my fix is effective or that my feature works
• I have added necessary documentation

[marcomangano]

I double checked this with the MDO Lab theme code to understand the changes. It makes a lot of sense to me, and I am fine with using this PR as a blueprint to update the other packages.

[ewu63]

@marcomangano @sseraj, what I mean by I'm not sure about the imports is that, even more stuff can be imported:

• autodoc_mock_imports could by default contain things like numpy and scipy
• html_theme could be imported too, which is a bit funny but will work.

Maybe it doesn't matter, and this PR as-is is more explicit.

[marcomangano]

Oh yeah @nwu63 , importing the html_theme is meta but it makes sense. About the autodoc_mock_imports, unless you want to import all the modules directly in the theme, I am fine with leaving them in the repo conf.py, together with the extensions. It makes sense for me as they are repo dependent and, even if some modules like numpy are probably coming up almost everywhere, it might be overly convoluted to have these imports in two separate arrays.
Anyway, we can go over a first refactoring of all the other repos, and move some autodoc_mock_imports into the theme at a later stage.

[ewu63]

Yes agreed, and leaving html_theme in there is more explicit so I am fine with that. In that case, let's go ahead with this approach and we can iterate in the future as needed.

[sseraj]

Would adding html_theme to the global config.py cause problems in requirements.txt? If not, I am inclined to adding it there and importing it.

[ewu63]

Nope, it should be fine. Alright, I'll update the package to make that available for import here.

[ewu63]

So I ended up adding all the built-in sphinx extensions to config.py, I think that's relatively clean. The extra ones like numpydoc should be specified per repo, and of course you need to make sure it's in the requirements.txt file for RTD to install. This build should pass

[sseraj]

Thanks! This looks good.

[marcomangano]

Looks very clean, let's extend this to the other repos!