NEP: numpy.org website redesign #14032
Conversation
|
@Shekharrajak you had some very useful input that I drew on for the initial version of this. I'd be happy to make you a co-author if you want. |
Yes! It would be my pleasure. |
|
Here are the few points that I am considering: Markdown based: So that technical writers don't have to worry about installation. They can write simply in .md file. Anyone can click on edit button shown in website (new feature) and contribute (edit/suggest changes for the page in Github) to make it better. This will engage users to add new content or edit content to improve it. Documentation Search: User should be having search box, so that they can easily and quickly find out relevant contents. Document Versioning: User should be able to switch between the old and new versions easily. They should be able to checkout old version details as well. Localization/Translation: User may have option to switch between languages. They should be able to read in native language as well. New release note and Blogs: Website should be updated with new blog posts and news about the current development and roadmap. So kind of blogging should be present in landing page. Fast development: Most of the SSG (Static Site Generator) frameworks are running in server and changes in file reflects immediately in UI. Also deploy and build process should be easy. Framework should provide flexibility to extend the features or add new features easily. So framework should have plugin system. Few other points I mentioned is here |
| 1. *Update current site.* A new Sphinx theme could be chosen. This would likely | ||
| take the least amount of resources initially, however, Sphinx does not have | ||
| the features we are looking for moving forward such as i18n, responsive design, | ||
| and a clean, modern look. |
There was a problem hiding this comment.
I disagree with this point. While I'm surely not a fan of Sphinx, it can have a clean modern look, and it has i18n support (not sure if there are limitations to it, but afaik content can be translated with .po files).
For pandas we're planning to do the opposite as this NEP proposes. We have https://pandas.pydata.org independent from the docs (it's also Sphinx, but could be any static website generator), and we're planning to integrate it with the docs, which should make things simpler to maintain.
We've got a prototype to experiment with the styles, you can see it here: https://dev.pandas.io/pandas-sphinx-theme/pr-datapythonista_base/. It's using https://github.com/ryan-roemer/sphinx-bootstrap-theme, the maintainers of the project have been helpful in the past, and they are open to adapt the theme for our needs.
It is responsive, and I would say the look is modern (at least compared to our current docs). If it's not, it can be improved with a designer modifying the css (I don't have great designing skills myself). I was experimenting on not having a navigation bar (that's why in the black header there are no links), but they come by default and we'll have them.
I'd personally be very happy to not have to deal with Sphinx, but since the plan is using it for the docs anyway, I think doesn't add much value to have a separate website, and two systems to maintain. Customizing Sphinx will require some work, but since we're going to do it for pandas, there will be no extra work to do for numpy/scipy.
And personally, I think the closer the docs/website of numpy, pandas and the rest of the ecosystem are, the better. Whatever is the final solution, I think we should follow the same approach, and also standardize the names of the sections and the main structure of the website/docs.
There was a problem hiding this comment.
I disagree with this point. While I'm surely not a fan of Sphinx, it can have a clean modern look, and it has i18n support (not sure if there are limitations to it, but afaik content can be translated with
.pofiles).
Thanks for pointing it out. I came across talk about Multilingual support for Sphinx. I will explore it.
The idea behind this is - We will write on simple english and out Statis Site generator will translate it to multi languages like the way docusaurus do : https://docusaurus.io/docs/en/translation
For pandas we're planning to do the opposite as this NEP proposes. We have https://pandas.pydata.org independent from the docs (it's also Sphinx, but could be any static website generator), and we're planning to integrate it with the docs, which should make things simpler to maintain.
We've got a prototype to experiment with the styles, you can see it here: https://dev.pandas.io/pandas-sphinx-theme/pr-datapythonista_base/. It's using https://github.com/ryan-roemer/sphinx-bootstrap-theme, the maintainers of the project have been helpful in the past, and they are open to adapt the theme for our needs.
Thanks for sharing these links.
It is responsive, and I would say the look is modern (at least compared to our current docs). If it's not, it can be improved with a designer modifying the css (I don't have great designing skills myself). I was experimenting on not having a navigation bar (that's why in the black header there are no links), but they come by default and we'll have them.
I'd personally be very happy to not have to deal with Sphinx, but since the plan is using it for the docs anyway, I think doesn't add much value to have a separate website, and two systems to maintain. Customizing Sphinx will require some work, but since we're going to do it for pandas, there will be no extra work to do for numpy/scipy.
Actually, the plan is having one website (numpy.org) landing page (and all other static pages like About, User Guide, News, tutorials ) will be generated using SSG (docusaurus/jekyll/Hugo) and numpy.org/docs will contain the generated build of Sphinx (which will be having Python API docstrings).
So it may engage reader/contributors to modify the Static file because it will be written in simple Markdown (like plain text), so need to setup SSG framework. Also writing blogs or news about numpy will be easy using SSG.
And personally, I think the closer the docs/website of numpy, pandas and the rest of the ecosystem are, the better. Whatever is the final solution, I think we should follow the same approach, and also standardize the names of the sections and the main structure of the website/docs.
There was a problem hiding this comment.
So it may engage reader/contributors to modify the Static file because it will be written in simple Markdown
I agree on this, but is this different than with Sphinx? If you're going to have the documentation in markdown for sphinx, having to maintain another system that does the same is what I don't understand. Or do you mean having markdown as opposed as Sphinx rst?
There was a problem hiding this comment.
we're planning to integrate it with the docs, which should make things simpler to maintain.
This is a no-go I think. The website builds in seconds, the docs take 10 minutes and require things like LaTeX. We even have a separate build for NEPs (which is fine in Sphinx), because people felt it was better to have that build fast.
While I'm surely not a fan of Sphinx, it can have a clean modern look
Everything is possible, but there are no examples of this I can think of (after a decade of all of us doing everything in Sphinx ....). Sphinx is for docs, not for websites. In theory you can build something like https://jupyter.org/ (or https://pytorch.org/ or https://www.tensorflow.org/) on Sphinx, but it will be extremely painful and much harder to maintain than Hugo or Jekyll.
I want to engage people with good web dev skills, rather than adapt the tool to the experience of the current maintainers. There won't be many web developers who will think it's reasonable to build a static site with smaller amounts of text but modern styling, some graphics, etc. in Sphinx.
We've got a prototype to experiment with the styles, you can see it here: https://dev.pandas.io/pandas-sphinx-theme/pr-datapythonista_base/.
That looks like a significant improvement over the current site, nice.
And personally, I think the closer the docs/website of numpy, pandas and the rest of the ecosystem are, the better.
That may be true. I'd rather follow Jupyter though, as the current best site in our ecosystem.
There was a problem hiding this comment.
I agree on this, but is this different than with Sphinx? If you're going to have the documentation in markdown for sphinx, having to maintain another system that does the same is what I don't understand. Or do you mean having markdown as opposed as Sphinx rst?
no we won't change the docs system - 1500 pages of text can't be changed away from Sphinx.
it's just about numpy.org, which right now has about 1.5-2 pages worth of text.
There was a problem hiding this comment.
thanks @datapythonista. that issue with Sphinx customization feels familiar:)
Meaning that if you have all together, and you want to change the home page, you need to wait for the next release for users to see it.
yeah, I don't think a 1-6 month wait is acceptable. also, the website is conceptually independent from a release.
Dealing with Sphinx is not great, but since you're going to use it for the docs, it's worth considering it for the website too
I'm having in mind that these are largely separate (groups of) people developing it. And in the end both are just a make html.
I don't think how nice the website looks depends much on what you use to generate the html
this is the point I disagree with most. experience shows that it's just not true for Sphinx. it may be true in theory, but that's like saying it doesn't matter whether you choose Perl or Python
pandas website is most of the time outdated,
the NumPy one too, and that's largely because people who care about code first and everything else second. we now have a good amount of energy from new people (with better web dev skills, or interest in educational materials, marketing, etc.).
There was a problem hiding this comment.
For what it worth, we have a separate repo for the astropy webpage, and it is indeed very nice not to be tied to the release cycle of the repo (including not to have a different webpage for LTS/bugfix/latest releases).
There was a problem hiding this comment.
I feel the need to respond to this thread since I wrote what we're discussing here in the NEP :)
I'll admit I took my own experiences with Sphinx into account without knowing much about its theming. I'll also admit I don't like Sphinx much, but it sounds like I'm not alone! At best, what I wrote in the NEP isn't very objective, so I'm open to editing this line.
I'd also like to preface I've been a front-end developer for years, so I'm hoping I can help steer a bit and correct any misconceptions, answer questions, and whatnot.
For me the trade off is between how annoying is to deal with Sphinx to customize the html, and how annoying is to maintain two separate systems.
If it truly is annoying to customize html in Sphinx, I think that alone is a dealbreaker for writing the landing page in Sphinx. You also mentioned:
Probably they are not making people who deal with the website have to clone the whole numpy, and how often you can release
I haven't cloned NumPy, but it already sounds large. I'd imagine this would slow down development for a relatively small landing page, and beyond that, I doubt we'd want releases focused around landing page changes.
Having the website separate has surely some advantages, but I don't think they are the building time, how good the website looks, or being responsive.
Build time is probably an advantage. I don't know how long it takes NumPy to build, but it sounds like it might take a little bit. Without NumPy (i.e. standalone Jekyll static page), build time should be seconds. You're right about the other two.
I don't think how nice the website looks depends much on what you use to generate the html (more on the amount of work you put in the css, and sphinx has a setting to specify your custom css files, that's trivial)
You're right :) However, you mentioned:
The good news is that the CSS is somehow independent of how the html is generated. So, I don't think it's a big deal to make the wrong choice to start with. The amount of work to move from Sphinx to Jekyll or the opposite should be much smaller than the work to create the CSS I think.
This unfortunately isn't accurate. I wish it was. CSS rules work differently depending on your HTML structure since CSS does care about parent/child elements. So given some really decent CSS, we couldn't port just the CSS without an identical HTML structure and expect it to work properly.
I think the docs and the website should be separated. However, it seems like there's consensus around the docs staying put in Sphinx for several packages (Pandas, AstroPy, etc.), which is great. I do think it would be a bonus if multiple packages did have the same styling, which would make navigating much easier for users of all packages.
There was a problem hiding this comment.
We mostly agree, just two things I didn't explain well and I think you misunderstood.
It's very easy to have the website in the docs, and be able to call something like doc/make.py --website-only and the website build will take couple of seconds. In pandas we're doing similar things.
Editting the CSS in Sphinx is trivial (same as in whatever else). The reason is more complex to add style is because changing the html is not as easy as just changing the template for things like the toc tree. That's why I said moving from Sphinx to Jekyll or the other way is doable; the work needed would be just to make the html the same (or close enough for the css).
Also, worth mentioning that for most parts of the website, changing the Sphinx templates should be enough, and for special pages (like the home in the pandas new look I sent) html can be used directly.
There was a problem hiding this comment.
Understood, thank you for clarifying!
|
First of all, choosing a few existing sites as examples to follow is the best thing to do. I like all the three sites selected by Ralf, especially that of Jupiter and Julia. Having such examples makes our job much easier (and also reduces our choices and discussions about possible choices). Indeed, if we want to make our site similar to Jupiter, we just fork it (https://github.com/jupyter/jupyter.github.io) and customize its content. If we want to make it similar to Julia, we just fork it: https://github.com/JuliaLang/www.julialang.org Both of them are in Jekyll and markdown, so this is the only choice (unless we want to make our site similar to that of pandas, which is built with sphinx). We admit that none of us is good as a web designer, so following the example of a nice website is the best way to go. I don't understand the need/requirement for translation or i18n. None of the sites that we are considering as examples have it, and I have not seen any other sites that have it. Maybe I am missing something. Can you show an example of a website with translation? By the way, I know this is not the topic of this NEP, but I think that we should follow the good examples for the documentation of the code as well. For example Jupiter and Julia: |
|
I propose to leave out translation. If a sub-community of users is interested in translating the website (or the docs) in their own language, they can just fork (clone) the website repo and translate it. And then take care of keeping it up to date. But it doesn't have to be the responsibility of the maintainers of the main website. |
|
Sphinx supports translation. Debian.org supports many languages. I think the proposal is to provide the infrastructure and accept PRs that supply the translated texts, not to translate ourselves. |
Yes, it can be done mostly by contributors only. So like https://docusaurus.io/, we can have project in Crowdin (like : https://crowdin.com/project/docusaurus)that will provide a platform for contributors to translate it online without setting up any development environment. |
|
I support the idea of having the docs and website separately. Docs and website maintenance practices are rather different. Most of the time they will be carried out by different community members since they require a different set of skills. |
|
Since we are having a graphic designer on our website redesign team this would be a good time to update the NumPy logo. I’m thinking nothing radical, just brining it to the 21st century.:) |
|
#WebsiteStructure |
Yes, this would be awesome. From here, "what are the best logo colors?: |
|
Sorry for the lack of updates this week - I haven't forgotten about this, but will be away for most of this week still. |
and don't forget about blue of data science 😉 |
From my perspective, the color combination is great regardless of what marketers say. (Check out the Ukrainian flag!) The shape is timeless and versatile. It just needs to be refined with modern tools. |
|
Thanks @InessaPawson. I incorporated your comments on structure and logo in the last commit. I plan to merge this NEP in the next 24 hours (coinciding with the Season of Docs announcements tomorrow). I will also propose it on the mailing list for acceptance. |
|
Okay all green so merging with "Draft" status. Sent email to the list and will change to "Accept" status in 5 days or so unless there are objections on the mailing list. Thanks for the useful ideas and feedback everyone! |
|
Probably worth mentioning the pandas new website proposal: pandas-dev/pandas#27870 After further analysis, I'm proposing to pandas also build the website separate from the docs (as in the proposal here). Feel free to comment in the pandas issue any idea, possible synergy... |
I'll send an email to the mailing list to discuss.
Cc @joelachance, @Shekharrajak