Documentation infra

[12rambau]

Maybe I didn't search enough but I failed to find the documentation build on the web. Could you share a public URL ?

[naschmitz]

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.

[12rambau]

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

[jdbcode]

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?

[12rambau]

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.

[12rambau]

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)

[jdbcode]

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).

[giswqs]

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

[giswqs]

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

[jdbcode]

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