POC: WIP: Redesign landing page of PyGMT website

[yvonnefroehlich]

Description of proposed changes

Currently trying out different ideas and approaches regarding improving the PyGMT website, especially the landing page. Seeing / experimenting how different layouts would look like, using grids, cards, buttons, and icons (xref: https://sphinx-design.readthedocs.io/en/rtd-theme/index.htm).

Fixes #4746

Disscussion (see also issue #4746)

• How many cards do we want?
• Use same structur as side bar? One card per main sections or cards only for specific topics?
• Coloring of cards? Globally or different for the landing page and External Resources?
• Add a new main section Project Overview (or similar)? Reorder sidebar partly?

Preview

• Landing page: https://pygmt-dev--4762.org.readthedocs.build/en/4762/
• Project Overview/Why PyGMT?: https://pygmt-dev--4762.org.readthedocs.build/en/4762/overview.html
• Project Overview/Citing: https://pygmt-dev--4762.org.readthedocs.build/en/4762/citing.html
• Project Overview/Conference Presentations: https://pygmt-dev--4762.org.readthedocs.build/en/4762/conferences.html
• External Resources: https://pygmt-dev--4762.org.readthedocs.build/en/4762/external_resources.html

(I)	(II) a	(II) b

Major changes

• Use cards on landing page
  • (I) Cards similar to the main sections: 6 cards as 3 columns and 2 rows (laptop) or vertical (smartphone), buttons for subsections
  • (II) a / b Card for specific topics: 9 cards as 3 columns and 3 rows (laptop) or vertical (smartphone)
• Add new section Project Overview
  • Why PyGMT
    • Project Goals <- from README
    • Background <- from Getting Started/Overview
    • Support <- from README (maybe rename to Funding)
    • Related Projects <- from README
  • PyGMT Ecosystem <- from Reference Documentation
  • Citing PyGMT with G^3 paper and Zenodo BibTex <- from README
  • Conference Presentations <- from Getting Started/Overview
• Reorder sidebar
  • Overview to Project Overview/Background, Conference Presentations (before Getting Started)
  • Minimum Supported Version to Getting Started (before Reference Documentation)
  • PyGMT Ecosystem to Project Overview (before Reference Documentation)
  • Changelog to Development (before Reference Documentation)

Make things look nice

• Centering text on landing page
• Vertical spaces between PyGMT logo and text on lading page
• Add icons to the headings of the cards
• Use buttons instead of bullet point lists

General things

• Add PyGMT logo on landing page via Sphinx markdown instead of html
• Links / URLs: In the README we use latest. This is fine for GitHub, but not optimal for the website as dev links to latest of the linked doc page not dev -> Rewrite text for docs, do not reuse from README
• Rename section Getting Help and Contributing to Getting Help -> Where?
• Sort tutorials on the External Resoures page by year (or date)
• Add possiblity to link to main sections -> Needed?

Resources

• https://sphinx-design.readthedocs.io/en/rtd-theme/index.html
• https://sphinx-design.readthedocs.io/en/rtd-theme/grids.html
• https://sphinx-design.readthedocs.io/en/rtd-theme/cards.html
• https://sphinx-design.readthedocs.io/en/rtd-theme/badges_buttons.html#octicon-icons
• https://sphinx-design.readthedocs.io/en/rtd-theme/badges_buttons.html#buttons
• https://sphinx-design.readthedocs.io/en/rtd-theme/css_variables.html
• https://sphinx-design.readthedocs.io/en/rtd-theme/css_classes.html

[seisman]

Perhaps move the changes of this file into a separate PR?

[yvonnefroehlich]

I agree it is better to have this in a separate PR. My idea is to keep it here to make it easier to see how the changed card design, especially the coloring, works for the Extral Resources page. Currently I change the colors in style.css globally. Maybe (I have to figure out how) it is also possible to change it only for the cards on specific pages or files. However, I feel it would be good to keep things consistent and not introduce more blue hues.

[seisman]

The README has remained unchanged, and much of its content is directly included in the documentation. What do you think about moving the detailed content to the documentation, linking to the relevant pages from the README, and keeping the README concise? I.e., having README and the landing page fully decoupled.

For example,

• the “Citing PyGMT” and “Minimum Supported Versions” sections could be replaced with links to their corresponding documentation pages.
• "Project goals" can be changed to "Feature Highlights" or similar
• "Support" can be fully removed from README

Some project README for reference:

• https://github.com/pandas-dev/pandas
• https://github.com/numpy/numpy
• https://github.com/pydata/xarray

[seisman]

• Use same structur as side bar? One card per main sections or cards only for specific topics?

I prefer option (I). It currently seems somewhat redundant with the sidebar, but that redundancy will disappear if we switch to the PyData Sphinx Theme (#4745), which does not include the same sidebar.

[seisman]

I don't think we should put minversions.md here. Very few users care about it.

[seisman]

"Project Overview" is really a good idea. What about adding it in a separate PR, so that this PR can be smaller for reviewing.

[yvonnefroehlich]

We can try this. But I am a bit afraid of merge conflicts due to overlapping changes, e.g., setting up the cards with the buttons is based on the structure of the documentation.

[seisman]

That is a valid concern, but smaller PRs generally make merge conflicts easier to resolve. We can split the changes into a few small and focused PRs:

• Add "Project Overview" and move the current "Overview"/"Ecosystem" section into this category
• Move presentations into "presentations.md"
• Add a new section "Citing"
• Rephrase the "Overview" section.

[seisman]

Actually, I feel "Changelog" should stay in "Reference Documentation".

[yvonnefroehlich]

• Use same structur as side bar? One card per main sections or cards only for specific topics?

I prefer option (I). It currently seems somewhat redundant with the sidebar, but that redundancy will disappear if we switch to the PyData Sphinx Theme (#4745), which does not include the same sidebar.

I also like option (I) most. The buttons provide a clear structure. I do not think that the redundant sidebar is a very big problem, because this is only relevant for the landing page; for all other pages, the sidebar can be helpful for navigating. Beside this, I think four to six cards are a good number. Nine cards could be too much and a bit overwhelming for users new on the website; thus, we would need to decide which of the current cards to drop (and if we want to have other topics as currently added as cards).