Python documentation duplication

[soxofaan]

I just noticed there is "getting started" documentation for the python client at https://openeo.org/documentation/1.0/python/ (src:https://github.com/Open-EO/openeo.org/tree/master/documentation/1.0/python), recently updated by @bgoesswe

At VITO we are also working on python client documentation hosted at https://open-eo.github.io/openeo-python-client/ (src: https://github.com/Open-EO/openeo-python-client/tree/master/docs)

I think there is already quite some overlap and duplicated effort we should avoid

[soxofaan]

cc @jdries

[bgoesswe]

It was discussed to have a commonplace and format for "getting started" articles for the clients (and maybe also backend drivers). I just did it for Python and QGIS as an example of how this could look like. When I was starting writing this for the Python client, the docs were outdated, so I assumed that it is not actively updated. But in general, I would say, to have a standardized way of getting started with openEO clients we need it on the website, but could link to the generated Python docs (which I would prefer anyway).
We could split it like that:

On the website:

• Very basic info about the client (which does not change that much)
• Installation instructions (a bit more detailed than the GitHub instructions for not so pythonous people)
• Maybe a quick example and a link to the GitHub docs.

On the GitHub docs:

• Usage / Examples
• API documentation

IMO, the documentation should be on Github as much as possible and the things on the website should just give a quick introduction. But it is up for discussion. We (TUW) will show our pilot users the How-Tos in the next weeks (depends on progress of the EODC backend) to get some feedback, maybe we get some useful input on how it should be arranged from there.

[soxofaan]

hi @bgoesswe , thanks for the feedback.

The docs in the Python client repo were indeed bit unmaintained for a long time, but we recently did some efforts to update them.

I agree with what you lay out there: having a basic starting point on the central openeo.org website and link to more extensive documentation on the python client website.

However, I'm not sure about putting the installation instructions on openeo.org website, because this is somewhat an "implementation detail" I would say. I think it's best to keep that close to the actual source code, to make it more maintainable when installation instructions would change.

Another detail: when you say "GitHub docs", you probably mean what we currently have at https://open-eo.github.io/openeo-python-client ? Or do you actually mean MarkDown based Github powered documentation? At the moment the docs are in RestructuredText, converted by Sphinx to static HTML, which is quite different from GitHub's Markdown tool chain.

[bgoesswe]

Sry for the late reply,

Yes, it seems legit to put the installation instructions to Github.

Yes, I meant the generated documentation at https://open-eo.github.io/openeo-python-client. So in the README markdown, I would just keep what is already there: The related links and the basic installation instructions.

[m-mohr]

I think the pip install command as the default way to install the library should be part of the getting started guide, but I think it's not so "getting started" to list the alternative way ("If you want to install the latest (unreleased) version ..."). That could just be a link to the library docs.

[m-mohr]

I removed the install instruction to install from source/GH. Having that done, I think this issue is solved, right?

[soxofaan]

I think there is still more opportunity to make the getting started docs more condensed, fight duplication and reduce the risk on outdated documentation, so can you reopen this issue @m-mohr ?

for example: about authentication: because it is tricky to explain this without scaring away the user I would keep it to the bare minimum to get the example working and refer to the more extensive client docs for details. The batch job part can also be dropped I think without loss of "getting started" value. I also think the overall structure of the getting started docs needs a bit of work: the document starts as a walk through but then halfway starts over with a new "example walkthrough".

[m-mohr]

I agree with the "walktrough" issue. I was also confused that it started over with a new example. In JS I then took that as opportunity to just give the complete code to copy&try.

For the other things mentioned I don't agree. Users need to authenticate in the future and we can't assume they are always using either Basic or OIDC, so it should be in there. And similarly for batch/sync. I think it's good to have batch in there as well, but maybe it needs a bit of restructuring regarding the chapter order.

[bgoesswe]

I just made a pull request with the latest "walkthrough" as a code example similar to the Javascript How-To and also added more references to the Python documentation in a pull request. Is that sufficient, or should we rethink the last walkthrough chapter in general?

[m-mohr]

Done. I renamed the walkthrough chapter to "Full example", which makes more sense now. I think it is quite good now. For OIDC you may also just refer to the Python docs, I did that in JS, too. OIDC is just so complex...

Anyway, we will let a user (he has no idea about openEO) try both Getting Started guides in the next week and we'll see how it works for him.

[soxofaan]

Users need to authenticate in the future and we can't assume they are always using either Basic or OIDC, so it should be in there.

I didn't want to suggest to say nothing about auth, just to keep it as simple as possible and refer to more in-depth docs for further details. As a matter of fact, I am currently working on OIDC related documentation in the Python client, but maybe it would be better to have client agnostic OIDC docs under openeo.org/documentation, that can be referred to from the respective docs of each client/platform, to properly explain some conceptual details (e.g. the different flows, the client id/credentials, ...) that are necessary to understand to work with OIDC. The respecive client docs can then just focus on practical details (which functions to call, ...)

I think it's good to have batch in there as well,

Indeed, batch can be in there, I just think the section can be shorter: I would just show the job.start_and_wait().download_results() snippet, which is the most useful "UI" for a novice user. The snippets about send_job/start_job/describe_job are not really necessary to just explain what is going on, and are only useful for more advanced usage.

Anyway, we will let a user (he has no idea about openEO) try both Getting Started guides in the next week and we'll see how it works for him.

that would be interesting indeed

[bgoesswe]

Indeed, batch can be in there, I just think the section can be shorter

Ok, yes I think it makes sense to shorten it, I would keep the send_job call, because otherwise as a user you do not know where the "job" is coming from as well as the job.start_and_wait().download_results() and drop everything else.

Anyway, we will let a user (he has no idea about openEO) try both Getting Started guides in the next week and we'll see how it works for him.

I think the Job class is not in the Python documentation yet. Should we keep the section as it is atm., so that the test user has this information?

But independent from the productive instance, I'll create a new pull request.

[m-mohr]

Has this been solved wrt openeo.org or what are the open action items? @soxofaan @bgoesswe

[bgoesswe]

Sry, I forgot to mention it here, but I adapted the Python documentation a few weeks ago (see commit: 9a4b2d5ae2a37cfb4c5895e2d7a8f686e4c927f5), like we discussed it and added more references to the official Python client documentation. So if that is fine with you @soxofaan, I would see this as fixed, otherwise I am also happy to make further changes the How-To on openeo.org.

[soxofaan]

I think it is fine to close this issue.

[clausmichele]

I just want to add my experience, since I have started to use the python client some time ago. I also found difficult to understand that there was a more complete documentation for the python client, since openeo.org points to https://openeo.org/documentation/1.0/python/ for the Python documentation. Ok, in the first lines there is a statement that points to the full docs, but I overlooked it. It may be better to make it somehow more visible (bigger in size and different in color?).

[m-mohr]

There are 17(!) links to the full documentation throughout the page. If someone overlooks all of those, I'm pretty sure many will also overlook whatever we add. 🤷‍♀️