search

pandas-dev / pandas

Flexible and powerful data analysis / manipulation library for Python, providing labeled data structures similar to R data.frame objects, statistical functions, and much more
https://pandas.pydata.org
BSD 3-Clause "New" or "Revised" License
43.37k stars 17.83k forks source link

New pandas website #27870

Closed datapythonista closed 2 years ago

datapythonista commented 5 years ago

xref: #15556

I've been thinking in more detail about the website, and I think it'll make things much simpler if we keep the pandas website and the documentation separate. My previous proposal was to unify everything, and use nginx rules to show the latest version (master) for pages that we want to show the latest version.

I still think that from the user perspective, there should be one single website, with one look and feel, a common header / navigation bar (no matter you're in the website or in the docs). It's easy to make it transparent that we're using different repos/hosts (with different domains or via nginx).

To keep things simple, I'd move from the docs (currently in this repo) to the website repo, everything in the website that doesn't make sense to show outdated (latest stable) versions, including:

I think this will make things much much simpler regarding Sphinx, will speed up a bit the documentation build, will avoid having to link users to the dev docs (like for contributing), and will simplify things in our workflow and the website set up. The only drawback I see is that we may have to repeat the main template, the css and the logo in both repositories. Those should change very rarely, and we can consider some CI check or automation (download them from one repo to another to build the docs).

For the documentation, I think with this approach will make more sense to create a custom (very simple) theme. This will make things easier and with the bootstrap theme I had some limitations that the maintainers don't seem so keen to address (dropdowns in the top navigation bar, customization in the levels of the sidebar...).

Another advantage is that I think we should be able to move much faster with this architecture when building the new website with the new design, compared to what would be with the Sphinx.

My proposed top-level structure is as follows:

I think the home page should be a visual and concise about us, so users new to pandas can very easily understand what the project is about.

For the blog, I'd mix the posts in the pandas blog, with a planet with the pandas related (tagged) posts of core devs, NumFOCUS, and anyone else we think it's worth.

For the Donate, NumFOCUS works with a new provider, that for what I've seen (I can be wrong), is able to handle the donations in an iframe, and not make users leave the page. I'd also include mentions to the institutional sponsors, comments from individual donors, and things like that.

Once there is agreement in the main structure, and we have a first draft, I'll open separate issues to discuss the exact details of the home, the community page, the blog and the donate page.

CC: @pandas-dev/pandas-core @stijnvanhoey

rgommers commented 5 years ago

The only drawback I see is that we may have to repeat the main template, the css and the logo in both repositories.

We have this issue with scipy.org, and handle it via a git submodule (scipy-sphinx-theme). Probably cleaner than via explicitly copying stuff around.

TomAugspurger commented 5 years ago

Seems reasonable. I suspect "Whatsnew" would be under "Documentation" as well, right?

On Mon, Aug 12, 2019 at 10:44 AM Marc Garcia notifications@github.com wrote:

I've been thinking in more detail about the website, and I think it'll make things much simpler if we keep the pandas website and the documentation separate. My previous proposal was to unify everything, and use nginx rules to show the latest version (master) for pages that we want to show the latest version.

I still think that from the user perspective, there should be one single website, with one look and feel, a common header / navigation bar (no matter you're in the website or in the docs). It's easy to make it transparent that we're using different repos/hosts (with different domains or via nginx).

To keep things simple, I'd move from the docs (currently in this repo) to the website repo, everything in the website that doesn't make sense to show outdated (latest stable) versions, including:

  • Install
  • Roadmap
  • Ecosystem
  • Contributing documentation

I think this will make things much much simpler regarding Sphinx, will speed up a bit the documentation build, will avoid having to link users to the dev docs (like for contributing), and will simplify things in our workflow and the website set up. The only drawback I see is that we may have to repeat the main template, the css and the logo in both repositories. Those should change very rarely, and we can consider some CI check or automation (download them from one repo to another to build the docs).

For the documentation, I think with this approach will make more sense to create a custom (very simple) theme. This will make things easier and with the bootstrap theme I had some limitations that the maintainers don't seem so keen to address (dropdowns in the top navigation bar, customization in the levels of the sidebar...).

Another advantage is that I think we should be able to move much faster with this architecture when building the new website with the new design, compared to what would be with the Sphinx.

My proposed top-level structure is as follows:

  • Home
  • Install
  • Documentation
    • Tutorials
    • User guide
    • API reference
  • Community
    • Contributing
    • Roadmap
    • Ecosystem
    • Discuss / Mailing list
    • StackOverflow
  • Blog
  • Donate

I think the home page should be a visual and concise about us, so users new to pandas can very easily understand what the project is about.

For the blog, I'd mix the posts in the pandas blog, with a planet with the pandas related (tagged) posts of core devs, NumFOCUS, and anyone else we think it's worth.

For the Donate, NumFOCUS works with a new provider, that for what I've seen (I can be wrong), is able to handle the donations in an iframe, and not make users leave the page. I'd also include mentions to the institutional sponsors, comments from individual donors, and things like that.

Once there is agreement in the main structure, and we have a first draft, I'll open separate issues to discuss the exact details of the home, the community page, the blog and the donate page.

CC: @pandas-dev/pandas-core https://github.com/orgs/pandas-dev/teams/pandas-core @stijnvanhoey https://github.com/stijnvanhoey

— You are receiving this because you are on a team that was mentioned. Reply to this email directly, view it on GitHub https://github.com/pandas-dev/pandas/issues/27870?email_source=notifications&email_token=AAKAOITQADK5HMLWQXCCHSTQEGAM5A5CNFSM4ILCRQJKYY3PNVWWK3TUL52HS4DFUVEXG43VMWVGG33NNVSW45C7NFSM4HEX5LRA, or mute the thread https://github.com/notifications/unsubscribe-auth/AAKAOIUOUBHEKML22TH3GRDQEGAM5ANCNFSM4ILCRQJA .

datapythonista commented 5 years ago

Seems reasonable. I suspect "Whatsnew" would be under "Documentation" as well, right?

Good catch, I forgot about those. I think it makes more sense to be in the documentation, yes. Otherwise when adding a new feature or bug fix, we would have to deal with two PRs one in the pandas repo, and one in the web. And I don't think we want that.

Updated the description, thanks for the feedback.

jorisvandenbossche commented 5 years ago

I agree it makes sense to keep the website and docs as separate repos. We want to be able to update the website independent of releases, and with a shared theme and layout it should be straightforward to blend them together.

One thing I am not sure belongs in the website repo is the contributing docs. I feel those belong much more in the core pandas repo, which also makes it easier to update them here (as it is here that the development and contributing happens). If the problem is that people generally want to see the latest dev docs for the contributing docs, We might be able to solve that in a different way. Eg by linking to the dev docs even in the stable menu (for the contributing part), or similar.

datapythonista commented 5 years ago

Something I'm thinking is that it doesn't make sense to have the docs and the website together, to be able to update the website more often than the releases. But may be we can have a web/ directory with the website in this same repo, and build and deploy from there separately. Probably this option has the best of both worlds (and a single repo would simplify things).

In any case, I think that can be decided once we have the website, and we can see more in practice what the different options imply.

datapythonista commented 2 years ago

The new website was deploy long ago, closing.