New pandas website #27870
Comments
datapythonista
added
Docs
Needs Discussion
We have this issue with scipy.org, and handle it via a git submodule ( |
|
Seems reasonable. I suspect "Whatsnew" would be under "Documentation" as
well, right?
…On Mon, Aug 12, 2019 at 10:44 AM Marc Garcia ***@***.***> 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
<#27870?email_source=notifications&email_token=AAKAOITQADK5HMLWQXCCHSTQEGAM5A5CNFSM4ILCRQJKYY3PNVWWK3TUL52HS4DFUVEXG43VMWVGG33NNVSW45C7NFSM4HEX5LRA>,
or mute the thread
<https://github.com/notifications/unsubscribe-auth/AAKAOIUOUBHEKML22TH3GRDQEGAM5ANCNFSM4ILCRQJA>
.
|
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. |
|
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). |
|
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 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. |
|
The new website was deploy long ago, closing. |
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
The text was updated successfully, but these errors were encountered: