POC: WIP: DOC/website: 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]

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.

[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).

[seisman]

I feel it would be much easier if we can resolve the conflicts now, rather than after finishing #4786.

[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).

Ping @weiji14 and @michaelgrund for preferences, other ideas and suggestions 🙂.

[seisman]

There are still conflicts to be resolved

[yvonnefroehlich]

There are still conflicts to be resolved

Hm. I am unsure what I should do here 🙁. We are still making changes to the README, the landing page (index.rst) and the overview page. I have added the versions of these files we have currently in #4786, but it's likely that they will change before the PR gets merged. So, will need to repeat this then.

[seisman]

Just click the Resolve Conflicts button, rather than copying files from another branch. After resolving the conflicts, we won't see the changes of citing.md and presentations.md in this PR.