Render PDEPs using myst-parser and the sphinx doc theme
State: closed

Quick experiment for the discussion in https://github.com/pandas-dev/pandas/issues/51461

- Individual PDEP pages are built with sphinx
- I injected a top navbar in the template mimicking the website's navbar, but for now just with a link back to the previous page. I think it _should_ be possible to let it have the same items/dropdowns as the other pages as well.

Some links to compare current rendering with the one from this PR:

- The roadmap page listing the PDEPs is still the same: https://pandas.pydata.org/preview/51467/about/roadmap.html
- Example PDEP with new rendering: https://pandas.pydata.org/preview/51467/pdeps/0004-consistent-to-datetime-parsing.html (vs https://pandas.pydata.org/pdeps/0004-consistent-to-datetime-parsing.html)


Labels:
name: Web
description: pandas website

Comments:
This is the preview of the changes here: https://pandas.pydata.org/preview/51467/pdeps/0001-purpose-and-guidelines.html

To me the benefits of this surely are not worth the extra complexity and inconsistency of UI of the PDEP pages. Can't really understand why you think this is a good idea. But if others also think it's a good idea, no big objection from my side.
Nice, thanks for doing this @jorisvandenbossche. Having the pydata-sphinx-theme styled code blocks is definitely very nice.

Is there a reason that we're only doing this for PDEPs? It would be nice to have the full website rendered using sphinx. 
(Would also make the website consistent with the docs in terms of style).
> Is there a reason that we're only doing this for PDEPs? It would be nice to have the full website rendered using sphinx. (Would also make the website consistent with the docs in terms of style).

That would make more sense to me than using two different systems for the website like in this PR.

The website parses the yaml config file and fetches data like the blog, releases... But those could be moved to sphinx extensions I guess.

I personally think it'd be better to put effort in providing an integrated experience of the web and the docs than migrating the whole website for some style changes we can easily achieve with the current website. But the final result seems to make more sense than the PDED hack, and if we implement the sphinx extensions in a third party package, those could be reused by other projects and remove a bit of complexity from our codebase.
This pull request is stale because it has been open for thirty days with no activity. Please [update](https://pandas.pydata.org/pandas-docs/stable/development/contributing.html#updating-your-pull-request) and respond to this comment if you're still interested in working on this.
Closing to clear the queue, but feel free to reopen when you have time to circle back
Is this still moving forward?
I would personally like to do that, yes, as I think it is a significant improvement in readability of the rendered PDEPs. But it needs some other people to indicate that they like it too (or not) to move forward.
/preview
Website preview of this PR available at: https://pandas.pydata.org/preview/pandas-dev/pandas/51467/
Example page to compare:

- https://pandas.pydata.org/pdeps/0007-copy-on-write.html
- https://pandas.pydata.org/preview/pandas-dev/pandas/51467/pdeps/0007-copy-on-write.html

There are certainly a few things that could be further improved (e.g. the breadcrumb is quite useless, but that is configurable and could be left out), but personally I find that the version of this PR gives a better readable page
I share @datapythonista's concerns on having a page on the website (outside of the docs) that doesn't share the theme. At a quick glance, I think we can change how the PDEPs are currently built to handle at least some of the issues in the OP of #51461, and would like to take a stab at that to see where I get.

Currently, the color theme is not great in my browser, but I presume that is easy to fix.

![image](https://github.com/pandas-dev/pandas/assets/45562402/de43eb90-6f27-42e6-b499-fda0c6e48a90)

> Currently, the color theme is not great in my browser, but I presume that is easy to fix.

Ah, yes (locally I don't default to dark theme, so didn't notice this). That can easily be forced to always be light (essentially defaulting to "light" and there is no button to change it on this page)
> concerns on having a page on the website (outside of the docs) that doesn't share the theme.

So then let's move the PDEPs out of the website, and then this argument is not relevant anymore? ;)

This is half a joke, but in practice, for example https://www.python.org/ has a link to the PEP index ("Documentation" dropdown -> "PEP index"), which then gives a page with a different styling. Similarly for numpy, the NEPs live in a suburl https://numpy.org/neps/ but built separately from the website and using different styling than https://numpy.org.

Personally, I think it is fine that the PDEPs are more part of the website while still using a different styling. Most people looking at the PDEP pages will also look a lot more at our docs than at our website, is my guess, so theming of the PDEPs using the doc style will actually feel more familiar
> Personally, I think it is fine that the PDEPs are more part of the website while still using a different styling.

I don't think it's desirable (regardless of others that may have done it), but also not a big deal. For me, the larger point is the tech debt introduced - we now have three styles to support: sphinx in docs, web page, and sphinx in web page. Still, if people find the style is worth it, I'm not opposed.
Looks like the discussion here has stalled and note sure if there's much interest moving forward with this, so closing to clear the queue