Testing overlap problems in docs

[choldgraf]

This changes the theme to the sphinx-book-theme so it's easier to notice issues on that theme specifically, and also adds some documentation blocks that highlight a few bugs that are present so we can more easily fix them in the future.

[chrisjsewell]

@choldgraf we should set up the testing the same as in sphinx-panels, to easily run the docs against different themes

[choldgraf]

@chrisjsewell yeah I agree - I really like that pattern. Do you think there's a way that we could generalize that pattern so that it's not a bunch of hand set-up for each repo?

[chrisjsewell]

see https://github.com/executablebooks/sphinx-panels/blob/master/tox.ini and https://github.com/executablebooks/sphinx-panels/blob/d25990bece19c33bb07975048f4843025fb179af/docs/conf.py#L68

[chrisjsewell]

Do you think there's a way that we could generalize that pattern so that it's not a bunch of hand set-up for each repo?

setting it up with the HTML_THEME environmental variable means the only difference in the branches is just the default theme: https://github.com/executablebooks/sphinx-panels/compare/alabaster-theme,
which is pretty general

[choldgraf]

thanks for those tips - I opened an issue to discuss documenting this + keep track of these links over here: executablebooks/meta#199

[choldgraf]

closing this because we now demonstrate this bug in our reference page: https://sphinx-copybutton.readthedocs.io/en/latest/reference/example.html