search

xarray-contrib / xdggs

Xarray extension for DGGS
https://xdggs.readthedocs.io
Apache License 2.0
79 stars 14 forks source link

getting started guide and tutorials #80

Closed annefou closed 3 weeks ago

keewis commented 4 weeks ago

@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 commented 4 weeks ago

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 commented 3 weeks ago

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 commented 3 weeks ago

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 commented 3 weeks ago

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 commented 3 weeks ago

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

allixender commented 3 weeks ago

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 commented 3 weeks ago

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)