Skip to content

Improve PyGMT documentation usability and consistency #4810

Description

@seisman

After redesigning the PyGMT documentation landing page and the project README (#4746), I feel it is a good time to further improve the documentation. Below are some documentation issues and ideas that we can discuss and address.

  • Improve version information shown in the footer. At the site footer, the dev version shows "Revision f8d331f" and the release version shows "Revision v0.19.0". I think it would be clearer to show "Release 0.19.0" instead of "Revision v0.19.0" for release versions.
  • Improve the "Full installation" page
    • Add an introductory note at the beginning, for example:

      The "Quickstart" section provides the fastest way to install PyGMT, whereas the following sections provide more detailed, step-by-step instructions for users with different setups or those who want to install the latest development version.

    • List both required and optional dependencies (DOC: List all dependencies in the instalation guides #4807).
  • Improve the "PyGMT Ecosystem" page
    • The page currently starts with "PyGMT provides a Python interface ...", which duplicates the Overview page. Since readers of this page likely already know what PyGMT is, this sentence could be removed.
    • The PyGMT Ecosystem includes both dependencies of PyGMT and packages that depend on PyGMT. The current introduction only describes the former, so the wording should be updated.
    • The ecosystem figure currently only shows PyGMT dependencies. Consider moving it to the "PyGMT dependencies" section.
    • Add GMT as a PyGMT dependency.
    • Currently, each package uses its name as a level-3 heading and includes the full official project description. Consider using MyST definition lists with shorter descriptions to make the page more concise.
  • Redesign the "Presentations" page using the card layout (DOC/website: Use card layout for presentations #4805).
  • Improve the "Changelog" page. Contributors are currently listed using Markdown lists, which takes up significant vertical space, especially in the PDF documentation(~700 pages). Consider using a comma-separated list instead, e.g., Author1, Author2, Author3.
  • Improve visibility of the PDF documentation. The PDF documentation has been available since v0.15.0 (Sphinx LaTeX PDF documentation bundle #1606), although there are still some limitations (Known issues in the PDF format of the PyGMT documentation #3813). Currently, the dev PDF is available at https://www.pygmt.org/dev/pygmt-docs.pdf, and release PDFs are attached as release assets. Consider ways to make the PDF documentation easier to discover.
  • Improve the "PyGMT Team" page. The page currently starts with four paragraphs of introductory text, which may be longer than necessary. Consider shortening it or moving some of the content into individual subsections.

Metadata

Metadata

Assignees

No one assigned

    Labels

    discussionsNeed more discussion before taking further actionsdocumentationImprovements or additions to documentationhelp wantedHelping hands are appreciated

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions