Documentation infra about xee HOT 11 OPEN

Why did you close my issue if the documentation is not build yet ? The Open-source community can clearly help on this topic me included

from xee.

Within the python community the most used documentation framework is Sphinx, it's creating from sources that resides usually in the "docs" folder any type of outputs: html, epub, pdf etc...

It has undreds of plugins more or less useful but allowing any customization you can think about (I myself maintain several of them) but also may themes (I also maintain one of them). It is used by state of the art python lib (pandas, xarray, ipywidgets, numpy....).

For deployment, the open-source go to choice is usually readTheDocs, which allow many cool features like multi-languages support, multi-version and my little favorite: PR pre-build.

The other big player in this game is mkdocs that is less customizable but might look easier for newcomers (note that if what you like about mkdocs is only the theme, then there is a Sphinx mirror of it).

I have lots of experience in that domain, my last example is the geetools documentation (WIP but deployed): https://geetools.readthedocs.io/en/latest/

If you get to the contribute section of the said documentation you'll notice that once everything is set up it's as easy as running a nox session to get the build locally and check the docs. Also all these things are parsing your docstrings so most of the content is still handled from the code.

from xee.

I can add a documentation website similar to geemap. I think the website can be hosted on this repo directly. The URL would be https://google.github.io/xee given that https://google.github.io is already active

from xee.

Hi @12rambau, we don't actually have the documentation built anywhere. The only documentation we have is a README file.

We plan on improving the documentation in the future, but we're short-staffed right now.

from xee.

Pierrick, I had suggested in our triage that we should be open to community members working on getting docs built. There may have been a misunderstanding. As Nate said, we are understaffed, and I think there is some concern that adding docs means we have one more thing to maintain and manage and it is not certain that we can always rely on the community. Before we commit to anything it would helpful for us to understand the options for community-oriented docs. Some things to consider:

• Ease of editing/configuring
• Easy of building and deploying
• Where to host
• Follow common practices in scientific Python domain
• Flexibility (do not want to get locked in hard to something)
• What are other Google-owned open repos doing
• What are the recommendations from Google Open Source team

Pierrick do you have any proposals - what would you recommend - do you have prior experience is a particular setup?

from xee.

looking closely to the existing Google docuemntation I think you embraced the mkdocs look and feel so you will want to go for https://jbms.github.io/sphinx-immaterial/ (the one used in geemap)

from xee.

Thanks for your analysis on this!

(The https://geetools.readthedocs.io/en/latest/ pages look great - well done!)

Given that geemap is using Sphinx + mkdocs - I'm inclined toward that combo to make the build / release / maintenance easier through consistency (we're already involved in maintaining and releasing geemap).

Maybe the remaining two things:

• Where to host (e.g., I think that the advertisements on readthedocs is not good for the Google-based repo/project)? I'll see if there is some Google domain that can be used.
• Ensuring that our doc sources are properly organized and sufficiently comprehensive. (We don't want to launch a docs site that is/looks incomplete or broken).

from xee.

Google already enables GitHub pages for the GitHub organization.
https://github.com/google/google.github.io

Repos under the organization can gave a subdomain. For xee, it would be google.github.io/xee

from xee.

I sent an email to Google Open Source team about using https://google.github.io/xee

from xee.

Google Open Source team was supportive of Sphinx, mkdocs-material, and GitHub Pages.
However, I think we should hold off on further docs enhancements until more kinks are worked out. In particular, we should support computed images and ensure that most projection/geometry/roi edge case issues are resolved. We should also have a better understanding of the use cases when Xee is appropriate and when it is not (expectations and limitations) so we can convey them clearly. Mostly this is for optics: with just a readme there is an "experimental project" vibe – with nice looking comprehensive docs there is a "completed project" vibe – I think we're still in experimental territory.

from xee.

Mostly this is for optics: with just a readme there is an "experimental project" vibe – with nice looking comprehensive docs there is a "completed project" vibe – I think we're still in experimental territory.

For this reason, I think readthedocs is a good solution. Using Google's github pages site is a bit more "official". readthedocs sites have a habit of being more experimental IMO. For example, Xee's sister project, weather-tools, is hosted on readthedocs via Sphinx. Same with Xarray-Beam. FWIW, I intended to set up a docs website there for this project (at initial release), but I ran out of time.

the documentation is not build yet ? The Open-source community can clearly help on this topic me included

@12rambau, I would love to have your help with writing documentation. How about this? — let me register a Sphinx site on readthedocs (I hold the keys for weathertools, for example) and I let the community (I also see your enthusiasm, @giswqs) fill in the missing gaps?

I’ve started writing docs here: https://github.com/google/Xee/blob/main/docs/why-xee.md

As far as an outline goes, I was following Xarray-Beam’s convention: https://xarray-beam.readthedocs.io/en/latest/

I like the style / template used in geetools! I would be so thrilled if we could get the same glam here. https://geetools.readthedocs.io/en/latest/

from xee.