Shall we use Sphinx to generate GPlately doc?

[michaelchin]

@GPlates/gplately-dev

I remember I brought this up before. But I forgot the decision we made. I am preparing the 2.0 release and have seen pygplates, PyBacktrack and plate-model-manager all using Sphinx. I start wondering it again mainly because all the Python packages belong to the GPlates software family. Maybe their doc should be in the same style.

If anything will happen, it will happen after the 2.0 release. We have plenty time to discuss.

"Built with Sphinx using a theme provided by Read the Docs."

https://www.gplates.org/docs/pygplates/
https://pybacktrack.readthedocs.io/en/stable/index.html
https://michaelchin.github.io/plate-model-manager/v1.2.0/

[jcannon-gplates]

There's some more discussion on whether to convert pdoc to sphinx in #213

If we do go with Sphinx we can still use numpydoc for the docstrings, like we currently are, so that's good.

I do admit that getting cross-references to work in pdoc (in the docstrings) was a little unsure. Pdoc uses backticks to reference other methods/attributes (which is nice and simple though). I guess not much difference there, eg, pdoc would be `PlateReconstruction.get_point_velocities` and Sphinx would be :meth`PlateReconstruction.get_point_velocities` (but you could change the link text to point velocities with something like :meth`point velocities<PlateReconstruction.get_point_velocities>`).

If anything will happen, it will happen after the 2.0 release.

After the 2.0 release sounds good.

I think the main difference would be outside of docstrings actually. I don't have any experience with pdoc there, but Sphinx is pretty good (once you learn the basics).

So we should probably decide before we start writing any significant documentation outside of the API/docstrings.

[dietmarmuller]

A comment about the current "Quick start" documentation. Its content currently does not comply very much with what a common understanding and purpose of a "quick start" doc is. A well-structured "Quick Start" guide for a Python library should be concise, clear, and provide an easy entry point for new users. It should focus on installation, basic usage, and a minimal working example to help users get up and running quickly. Best Practices for a Quick Start Guide:
Keep it short and to the point – Users should get started in minutes.
Use code examples – The quickest way to understand usage.
Avoid unnecessary details – Deep explanations should be in full documentation.
Use links for more details – Keep the guide clean but allow deeper exploration.

This is what a quick start guide for GPlately should perhaps look like:

Quick Start Guide for gplately

gplately is a Python library that facilitates plate tectonic reconstructions and integrates with pygplates. This guide helps you get started quickly.

Installation

1. Create a Conda Environment (Recommended)
   bash
   Copy
   Edit
   conda create -n gplately_env python=3.10 -y
   conda activate gplately_env
2. Install gplately and Dependencies
   First, ensure you have pip installed:

bash
Copy
Edit
pip install --upgrade pip
Then, install gplately:

bash
Copy
Edit
pip install git+https://github.com/GPlates/gplately.git
Alternatively, clone and install manually:

bash
Copy
Edit
git clone https://github.com/GPlates/gplately.git
cd gplately
pip install .
3. Install pygplates (Required)
Download pygplates from the GPlates website and install it according to your OS.

For example, on Linux:

bash
Copy
Edit
pip install pygplates-0.36.0-cp310-cp310-linux_x86_64.whl
Minimal Working Example
After installation, you can start using gplately for plate tectonic reconstructions:

python
Copy
Edit
import gplately

Load a model (default model provided)
model = gplately.load_model()

Define a point (Longitude, Latitude)
point = (120, -30)

Reconstruct the point to 100 Ma
reconstructed_point = gplately.reconstruct_point(point, time=100)

print(f"Reconstructed coordinates at 100 Ma: {reconstructed_point}")
Common Use Cases

1. Reconstruct a set of points
   python
   Copy
   Edit
   points = [(120, -30), (100, 20), (-80, 50)]
   reconstructed_points = gplately.reconstruct_points(points, time=100)

print(reconstructed_points)
2. Generate a Rotation Model
python
Copy
Edit
rotation_model = gplately.load_rotation_model("path/to/your_rotation_file.rot")
3. Compute Plate Motion Vectors
python
Copy
Edit
plate_velocity = gplately.compute_plate_velocity(lon=120, lat=-30, time=100)
print(f"Plate velocity: {plate_velocity}")
Troubleshooting
Error: ModuleNotFoundError: No module named 'pygplates'
→ Ensure pygplates is installed manually from GPlates.

Error: pip install fails due to pygplates
→ Install pygplates separately before installing gplately.

Error: ImportError: gplately not found
→ Check if your environment is activated:

bash
Copy
Edit
conda activate gplately_env
Next Steps
🔹 Explore the full documentation.
🔹 Check out example notebooks in the GitHub repository.
🔹 Join the GPlates community at www.gplates.org.

Conclusion:
My main point is that GPlately2.0 will need a quick start guide that complies with what a quick start guide is supposed to be. This is especially important for attracting new users. In addition, the variety of uses cases needs to be extended and cover end-user communities such as the paleoclimate community and the critical minerals community.

[michaelchin]

Thanks @dietmarmuller

We have another Discussions thread discussing the "Quick start" section. I will link your comment in that thread.