getting started guide and tutorials

[annefou]

No description provided.

[keewis]

@annefou, I've taken the liberty to modify your PR. In particular, I changed everything to use myst markdown instead of restructuredtext (which sort of works except for the API reference).

My plan is to add tutorials specialized on H3 and healpix (and I did remove @tinaok's example because while that is great, it is designed to be a separate notebook), and in the future to add pages to the user guide that describe the supported DGGS, which libraries are used to support them, and possibly links for further reading / helpful libraries.

[keewis]

I've also noticed that the lonboard map somehow interferes with the notebook headings (for both nbsphinx and myst-nb). Not sure how to resolve that. @benbovy, do you have any ideas (or time to review)?

Edit: I've reported a bug in lonboard, let's see what comes out of that

[keewis]

I believe for a first version of the documentation this should be ready for reviews (see the preview). In particular, do you any have suggestions regarding the format of the publications page or any additional entries? I'm not so sure of that, since it's basically a single list item containing a link.

I've activated the repository on zenodo, so for each release we should get a DOI, but I believe we still need to create a CITATIONS.cff file to populate the authors.

cc @annefou, @allixender, @tinaok

[annefou]

It looks very good! One remark: I find it a bit weird to have a section called "User guide" with only references. For the references, I think we should add a few more; at least : 10.5194/isprs-archives-XLVIII-4-W12-2024-75-2024.

What do you think about using BibTeX for the references? It makes it much easier to manage, cite, and format properly. I think there is a bibtex extension for sphinx (or maybe something better).

[keewis]

I find it a bit weird to have a section called "User guide" with only references.

That's true. I was thinking we'd add more elaborate descriptions of the DGGS to the user guide, after which it would not be as weird. We could also move it to the "technical information" and name it "reference guide" or something?

What do you think about using BibTeX for the references?

I don't have a strong opinion on this, which is why I was hoping for your input. If you'd like to use sphinxcontrib-bibtex (or maybe the bibtex support in myst? Not sure if that is also available in myst-parser), feel free to.

[allixender]

Markdown and myst would be a nicer user experience. But references management with bixtex would also be nice.

[allixender]

I would be nice to have slightly more elaborate sections on the different supported DGGS. I'd be happy to contribute. LEt me know how and where?

[keewis]

LEt me know how and where?

I imagine this would be hard for you to do, so I'm going to go ahead and merge to get the current state to main, and then you can just open a new PR adding the DGGS descriptions to the user guide (and another for the references / bibtex)