Overhaul documentation (pydata_sphinx_theme)

[yann1cks]

Hello Raphael,

initially I wanted to make some small changes to the docs navbar, because it does not use the correct html elements and the missing top-margin on "Functions" bothered me.

Instead I overhauled the whole docs using the PyData Sphinx Theme. This sphinx theme is based on Bootstrap and used by most (all?) PyData projects and some others projects (e.g. Anconda). It is actively maintained, based on the newest Bootstrap version and has multiple improvements. I think it is the obvious successor to sphinx_bootstrap_theme.

This PR is only a first step and many parts of the docs are not working correctly. Before continuing I want to make sure that you would accept a PR that overhauls the docs. The following todos are still left. I would need your input for some of these:

• Finalizes primary and secondary colors for pingouin (see Anaconda Docs)
• Navbar:
  • (Input needed) Add a donation entry
  • (Input needed) Add a cite entry
  • (Input needed) Add "User guide" section which combines10 minutes to Pingouin and Guidelines
  • Restore navbar item names
• (Input needed) Add/remove search
• Refactor conf.py
• Migrate to sphinx-design. sphinx-panels is not maintained.
• (Input needed) Add dark mode support (colors, plots, logos)
• Reduce package size.
• Remove build/html/ from url path. (Needs to be fixed on the server)

Selecting correct colors and adding a working dark mode are the most complicated parts. The rest is really straight forward.

Regards
Yannick

PS: Sorry for the failed CI. I didnt run black on the conf.py file.

[raphaelvallat]

Hi @yann1cks,

Thank you very much for opening this PR. I'm all in for updating/refactoring the doc — this is long overdue. Using PyData Sphinx Theme sounds great.

Here are some first answers to your questions:

• (Input needed) Add a donation entry: No need
• (Input needed) Add a cite entry: Yes please
• (Input needed) Add "User guide" section which combines10 minutes to Pingouin and Guidelines: I kind of want to deprecate the latter in the future so I'm not sure about including it. I'd say no need for now. I'd like to create a more detailed "Quick start" page later on.
• (Input needed) Add/remove search: Add
• (Input needed) Add dark mode support (colors, plots, logos): No need

Please let me know if you have any other questions and/or how I can help.

Thanks again,
Raphael

[yann1cks]

Hi Raphael,

thank you very much for your quick response. Most of the todos mentioned above are done. Please have a look at the reworked version of the documentation and let me know what you think. A secondary color is required and I used a dark orange (#d46700) to go with the a penguin theme. It looks a quite similar to the jupyter colors. Alternatively a dark gold/yellow (#a78004) or dark purple (#a34980) could work. You can change the css variable --pst-color-secondary to compare the colors.

It was easier than expected to add a dark mode. So I just went ahead with it. I also added a 404 page and removed the accordions from the FAQ page, because they used lots of raw html. I added all docs dependencies to the pyproject.toml file. You can use pip install --upgrade pingouin[docs].

Replacing the Guidelines with a proper quick start section sounds great. I did not change the 10 minutes to Pingouin and Guidelines pages.

The "Edit on GitHub" and "View Source" links are not working properly.

At the moment every url looks like this "https://pingouin-stats.org**/build/html**/index.html". It should be possible to shorten the url by removing the bold part with some server settings, but a redirection of the old urls would be nice.

[raphaelvallat]

Hi @yann1cks — sorry for the late reply. This is really great work. The new documentation looks really beautiful 👏 I'll merge this PR now and will create a new release of Pingouin.

At the moment every url looks like this "https://pingouin-stats.org**/build/html**/index.html". It should be possible to shorten the url by removing the bold part with some server settings, but a redirection of the old urls would be nice.

I tried to have a look at how to enable this but my web skills are pretty limited unfortunately and I could not find an easy way to do this.

[yann1cks]

I tried to have a look at how to enable this but my web skills are pretty limited unfortunately and I could not find an easy way to do this.

Hi Raphael, thanks for merging the docs! It’s impossible to guess the issue with the url. I could try to setup hosting with GitHub Actions. That’s not difficult and works fine with a custom domain. (And it is possible to automate the docs release with GitHub actions.)

[raphaelvallat]

Hi @yann1cks,

That could be a great option. What would you need to get started with this? As of now, I'm uploading the generated files to an AWS S3 bucket.

FYI I used to host the static doc directly on GitHub back in 2018-19, but decided to change to S3 because it was annoying to have to commit all the generated files to git every time I re-generated the doc.. I'm sure there is (and there was) a better way to do this.

Thanks so much for your help,
Raphael

[yann1cks]

I need nothing. I can just test in my fork and write a pull request if it works.

It’s basically this tutorial:
https://www.sphinx-doc.org/en/master/tutorial/deploying.html#id5

GitHub Actions is used to build the docs, either triggered manually or with every release. The built html is moved to a different branch, so trunk doesn’t get messy.