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.