Open-EO
Documentation improvements
A couple of ideas to improve the docs at https://open-eo.github.io/openeo-python-client/
- [x] landing page is now just table of contents, we probably should make it more compelling with a bit more text/images
- [x] add link to changelog (e.g see structlog https://www.structlog.org/en/stable/changelog.html )
- integrate working examples in some way (embed scripts directly, embed notebooks)?
- any quick way to visually align better with openeo.cloud?
- better, more modern theme (e.g. furo as metnioned in #294)
- versioning of documentation: have a separate documentation build of latest release and a documentation build of latest master
- not sure if this might be useful here: https://github.com/jimporter/mike
- add a documentation page with code style recommendations, focused on openEO usage patterns. (also noted under #294 )
- better "Getting started" page (currently https://open-eo.github.io/openeo-python-client/basics.html ): e.g. follow structure of https://docs.openeo.cloud/getting-started/python/ and #308
- [x] ~use sphinx "fulltoc" sidebar instead of only local toc (see https://sphinxcontrib-fulltoc.readthedocs.io/en/latest/index.html)~ just use globaltoc.html iso localtoc.html
- Also inspiring: https://nox.thea.codes/en/stable/ uses alabaster theme, but it looks better than the default we are using, includes changelog page
- use
code-blockdirectives with proper languages: python, pycon (for Python REPL style snippets), console (for bash/shell)
- use the ipython sphinx directive (https://ipython.readthedocs.io/en/stable/sphinxext.html) for python snippets where the output is automatically generated from input statements, so it's easier to make sure snippets are valid and up to date. xarray docs use this for example: input rst -> output
- also an interesting sphinx theme to consider: https://github.com/pydata/pydata-sphinx-theme it's used by pandas, numpy, scipy, jupyter, ...
FYI: Shapely 2 was released today and apparently they refreshed the look of the new shapely docs using this theme https://sphinx-book-theme.readthedocs.io/en/stable/ if I'm not mistaken
One thing I've also seen elsewhere is this table of contents for the current page on the right. Would be nice if we can also enable that for our docs.
Jeroen Dries TAP - Centre for Remote Sensing and Earth Observation Processes VITO NV | Boeretang 200 | 2400 Mol tel. +32 14 33 55 11 | @.https://outlook.vito.be/OWA/redir.aspx?C=bkbvq29Z1EO1hvVK0QJMbACOitzQ7c8Ip7CWFVkhZV75OTezDjCIkdDzkCq1rif2MTOFHY6bxtg.&URL=mailto%3avoornaam.naam%40vito.be @.@.@.@.***https://outlook.vito.be/OWA/redir.aspx?C=bkbvq29Z1EO1hvVK0QJMbACOitzQ7c8Ip7CWFVkhZV75OTezDjCIkdDzkCq1rif2MTOFHY6bxtg.&URL=https%3a%2f%2fwww.facebook.com%2fVITObelgium
From: Stefaan Lippens @.> Sent: Monday, December 12, 2022 5:45 PM To: Open-EO/openeo-python-client @.> Cc: Subscribed @.***> Subject: Re: [Open-EO/openeo-python-client] Documentation improvements (Issue #285)
FYI: Shapely 2 was released today and apparently they refreshed the look of the new shapely docshttps://eur02.safelinks.protection.outlook.com/?url=https%3A%2F%2Fshapely.readthedocs.io%2Fen%2F2.0.0%2F&data=05%7C01%7C%7Ce24f469e3a154ce5971a08dadc60390c%7C9e2777ed82374ab992782c144d6f6da3%7C0%7C0%7C638064603077115083%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=Mt1%2FOEHA3JwZ4nRkvqH4SMW7S6WOMCZyAWm7t3ejI%2FQ%3D&reserved=0 using this theme https://sphinx-book-theme.readthedocs.io/en/stable/https://eur02.safelinks.protection.outlook.com/?url=https%3A%2F%2Fsphinx-book-theme.readthedocs.io%2Fen%2Fstable%2F&data=05%7C01%7C%7Ce24f469e3a154ce5971a08dadc60390c%7C9e2777ed82374ab992782c144d6f6da3%7C0%7C0%7C638064603077115083%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=27NZCPXElDWiokDR%2FFttSjuIjMp%2FTi2PW%2BAcdxHpAzw%3D&reserved=0 if I'm not mistaken
— Reply to this email directly, view it on GitHubhttps://eur02.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2FOpen-EO%2Fopeneo-python-client%2Fissues%2F285%23issuecomment-1346856060&data=05%7C01%7C%7Ce24f469e3a154ce5971a08dadc60390c%7C9e2777ed82374ab992782c144d6f6da3%7C0%7C0%7C638064603077115083%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=ULUHbC8P87etUryrXcZDMHTUYbacyJEweEPd%2Fc7pBe4%3D&reserved=0, or unsubscribehttps://eur02.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Fnotifications%2Funsubscribe-auth%2FABNJPSAOJDHIYNERUL62WS3WM5JBBANCNFSM5RONXC2Q&data=05%7C01%7C%7Ce24f469e3a154ce5971a08dadc60390c%7C9e2777ed82374ab992782c144d6f6da3%7C0%7C0%7C638064603077115083%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=3KcbW%2BN3SVCbA%2BSkb9Aoa0QfBec1ChYTvzaSwh9hh9M%3D&reserved=0. You are receiving this because you are subscribed to this thread.Message ID: @.***>
VITO Disclaimer: http://www.vito.be/e-maildisclaimer
Another thing to consider: in #390 ProcessBuilder docs were added to the API docs: https://open-eo.github.io/openeo-python-client/api-processes.html . The ProcessBuilder docs however are directly copied from the openeo-processes specs, which is in Markdown format, while the current API docs assume the doc blocks are ReStructuredText. It's not really noticeable for a large number of processes (although bold/italic/monospace is messed up), but it goes wrong for some more complex processes which use lists or other constructs.
I noticed that pytest docs switched from alabaster (on https://docs.pytest.org/en/7.1.x/) to furo (https://docs.pytest.org/en/8.2.x/) giving it a more modern feel