Skip to content

Switch to pydata sphinx theme #4761

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Jun 18, 2021
Merged

Switch to pydata sphinx theme #4761

merged 5 commits into from
Jun 18, 2021

Conversation

OriolAbril
Copy link
Member

This PR changes the theme to pydata sphinx theme and also fixes many long standing issues
with the documentation like the search function not working, the non-existance of tables of contents
or adding links to the source code. Some of these fixes are thanks to the theme change,
others are somewhat independent.

Pros of the PR:

  • We don't have to maintain a custom theme with lots of css, pure html and javascript.
    This is a particularly important pro because we were not maintaining the theme, so it
    progressively broke over time.
  • Automatic tables of contents! The left sidebar has the section level table of contents, the right
    sidebar the page level table of contents. Moreover, the left table of contents is foldable,
    so with the right reorganization each notebook will have a notebook level table of contents and
    a section (examples or tutorials) level toc which is foldable by sections.
  • Search bar works again
  • Links to source code from API docs (theme independent)
  • Looks better IMO

Cons/TODOs:

  • We have to restructure the documentation a bit
    • pymc-examples -> I think we should move away from javascript and use pure rST/MyST with
      sphinx_panels
    • learn page: more or less the same
    • A lot of the pure html will need to be updated because we are changing the bootstrap major
      version docs are built on -> this is also a pro because couples with cool extension like sphinx
      panels means we won't have to care about bootstrap anymore, everything will be updated by these
      extensions

* remove extra custom css from build
* add github and twitter icons
* move search bar to navbar
* add version number
* remove sidebars from home page

left to do:
* fix gallery generator -> stop using javascript
* fix home page
* move away from so much custom html -> myst markdown?
@OriolAbril OriolAbril marked this pull request as draft June 10, 2021 19:05
@OriolAbril
Copy link
Member Author

I have converted the learn.rst file (which was only raw html) to myst and kept most of its appereance intact thanks to sphinx-panels extension. The new file is shorter in both number and lenght of lines and easier to read.

Here is how it looks:

image
image
image

@OriolAbril OriolAbril marked this pull request as ready for review June 17, 2021 14:16
@OriolAbril
Copy link
Member Author

I think we can merge like this and fix the pages that still need some work between now and the first 4.0 release, in a follow-up or multiple follow-up PRs.

@twiecki twiecki merged commit f4343ca into main Jun 18, 2021
@OriolAbril OriolAbril deleted the docs_theme branch June 18, 2021 09:14
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants