WEB/DOC: Move not versioned pages from the documentation to the website

[datapythonista]

We built the website independently from the documentation, since not all our content is version dependent. For example, the documentation of read_csv needs to be repeated for 1.4, 1.5, 2.0... So we want it implemented in Sphinx and released at release time. But for other pages such as the code of conduct, team, installation instructions... there is no value in having different versions, since things become obsolete immediately after changes.

When the website was implemented, new pages that didn't require versioning were created in the website, but existing pages were not moved, and in some cases duplicated. This was never addressed, and it's causing small problems of users getting information from obsolete sources (for example, the recent #53315).

The pages that in my opinion shouldn't be in the docs but in the website are:

• The whole development section, including the roadmap subsection, which is an obsolete duplicate of the version in the website as far as I know
• The release notes. This one is more controversial. It doesn't make sense to have more than one version, and backporting notes is annoying and not really needed. But the release notes refer to API pages almost in every item, and this can be done simpler with Sphinx than with our website. Not sure how difficult it could be to implement a shortcut to make referencing API pages simpler and safer. We could use intersphinx to validate that no broken links are used. But in any case, this is not as trivial as with other pages, and I personally don't have a strong opinion on whether it's worth or not.

@pandas-dev/pandas-core thoughts?

[MarcoGorelli]

sounds fine 👍

[rhshadrach]

The development docs also make internal references to various doc pages. As long as we can maintain that functionality, I'm not opposed.

I expect to find changelog/release notes/whatsnew in a project's documentation, but would be satisfied if we can keep a link there (in a visible spot).

[phofl]

I prefer keeping the release notes in the docs

We should try to align the style of our website with how our docs look before moving more stuff to the website imo

[datapythonista]

Fully agree with that. I think just having the website bar visible in the docs should be a huge improvement.

I also just realized that there is another implication on moving the release notes to the website. We don't want to publish the release notes in real time. They should be published for a version when it's released. Not great to have the duplication... But the alternative doesn't seem much better either.

[jorisvandenbossche]

If it's the duplication we worry about, we could also delete the whatsnew pages in the older doc versions and replace those pages with a redirect to the stable version of that page (I think that should be quite easy to automate with a small script to be run after a release).

[topper-123]

I think just having the website bar visible in the docs should be a huge improvement.

Yes 😄 !

[tpaxman]

I would add my vote for this issue, as I encountered the same issue reported in #53315 while attempting to setup a development environment: , i.e., Google sent me to these outdated instructions:

https://pandas.pydata.org/docs/development/contributing_environment.html

instead of the current instructions:

https://pandas.pydata.org/docs/dev/development/contributing_environment.html

[bashtage]

It mostly seems like a good idea, but it can lead to problems. For example, if someone wants to compile pandas 1.x from scratch (perhaps making a change locally, but not for development), then the modern instructions that will discuss meson will not be correct. The instructions in the 1.x docs will be correct.

[jorisvandenbossche]

Specifically for the development docs, we could also add a banner notifying people they probably want to check the dev version of the docs (if they are in the development section and are not in the dev version of the docs).
For the arrow docs we did something similar, see eg https://arrow.apache.org/docs/developers/overview.html

That's maybe not the perfect long term solution, but it should be relatively easy to add and I think it already provides a useful pointers for contributors visiting that section of the docs site to remind them to go to the dev version.