WEB: Refine PDEP presentation

[rhshadrach]

• [x] closes #51461 (Replace xxxx with the GitHub issue number)
• [ ] Tests added and passed if fixing a bug or adding a new feature
• [ ] All code checks passed.
• [ ] Added type annotations to new arguments/methods/functions.
• [ ] Added an entry in the latest doc/source/whatsnew/vX.X.X.rst file if fixing a bug or adding a new feature.

Alternative to #51467. I believe this address all items in the linked issue. The main benefit in not switching to publishing PDEPs in sphinx is that it then matches the style of the rest of the webpage.

This is just a rough version to demonstrate what's possible, some refinements (highlighted below) need to be made if we are to merge this.

[rhshadrach]

/preview

[github-actions[bot]]

Website preview of this PR available at: https://pandas.pydata.org/preview/pandas-dev/pandas/58791/

[rhshadrach]

PDEP6 shows code highlighting.

cc @jorisvandenbossche @datapythonista

[jorisvandenbossche]

@rhshadrach thanks a lot for looking into this!

I certainly think this is a nice improvement, and if we don't have agreement on using sphinx instead, we should definitely merge this one. But if you ask my honest opinion, I personally still think https://github.com/pandas-dev/pandas/pull/51467 gives the better result.

Concrete feedback on the changes here:

• The header links need some offset (it doesn't know about the top navbar). Eg https://pandas.pydata.org/preview/pandas-dev/pandas/58791/pdeps/0006-ban-upcasting.html#detailed-description

  I think with the sphinx theme this is solved with

  html {
    scroll-padding-top: calc(var(--pst-header-height) + 1rem);
  }
  

  (and here this can be be fixed number, I assume)

• I would personally further reduce the width

[Aloqeely]

Personal preference, but I think the "On this page" sidebar (from @jorisvandenbossche's PR) is cleaner and resembles the docs more than the table of contents here. (I guess that's a benefit of using Sphinx?)

[github-actions[bot]]

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.