Render PDEPs using myst-parser and the sphinx doc theme #51467
Conversation
jorisvandenbossche
force-pushed
the
pdep-sphinx-rendering
branch
from
65882ba
to
8e92ff6
Compare
| @@ -0,0 +1,20 @@ | |||
| # Minimal makefile for Sphinx documentation | |||
There was a problem hiding this comment.
Those Makefile and make.bat files are not actually needed, but we could keep them in case you locally just want to build the PDEPs (although then you can also run sphinx-build -M html . _build, so that might not be worth it)
web/pandas_web.py
Outdated
| @@ -363,6 +363,8 @@ def get_source_files(source_path: str) -> typing.Generator[str, None, None]: | |||
| Generate the list of files present in the source directory. | |||
| """ | |||
| for root, dirs, fnames in os.walk(source_path): | |||
| if root.startswith("pandas/pdeps"): | |||
There was a problem hiding this comment.
This could be generalized by allowing a directory in the ignore field in config.yml
|
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. |
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 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. |
jorisvandenbossche
changed the title
|
/preview |
|
Website preview of this PR available at: https://pandas.pydata.org/preview/pandas-dev/pandas/51467/ |
|
Example page to compare:
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.
|
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) |
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 |
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. |
Quick experiment for the discussion in #51461
Some links to compare current rendering with the one from this PR: