documentation for openradar projects

[kmuehlbauer]

While working on xradar documentation I found we could make use of rtd subprojects in connection with custom domains.

The url would look something like:

• Main doc site: https://docs.openradarscience.org/en/latest
• Project doc site: https://docs.openradarscience.org/projects/xradar/en/latest

Interested projects could be added to this as well, for wradlib this would look like

• https://docs.openradarscience.org/projects/wradlib/en/latest

The only thing we would have to do is setting up the docs.openradarscience.org. The projects would be added as subprojects according to the instructions in the above link.

To have the documentation of xradar associated with openradarscience.org I'll go forward making the needed changes.

That include:

• Setting up a parent docs repo in openradar. In this documentation we could just link to the different available projects. Also some information about external associated documentation might be nice (currently eg Py-ART, LROSE, BALTRAD, wradlib, pysteps etc.).
• Linking docs.openradarscience.org with RTD
• Adding xradar as subproject.

[kmuehlbauer]

OK, here we go:

The stub docs page is now here:

https://docs.openradarscience.org

xradar documentation is now available here:

https://docs.openradarscience.org/projects/xradar

[kmuehlbauer]

The "Docs" page is now available also via link from https://openradarscience.org.

There are many options to make this more integrated, eg. via a image link. But we will eventually find out.

[kmuehlbauer]

@openradar/developers

Please have a look at the documentation and share your comments/critics here.

@mgrover1 swapped our landing page over to this very repo. The documentation is hosted via gh-pages here: https://openradarscience.org.

I've added repo https://github.com/openradar/openradar-docs which incarnates as https://docs.openradarscience.org.

The new xradar repo (https://github.com/openradar/xradar) documentation is here (https://docs.openradarscience.org/projects/xradar/en/latest/).

We might think about removing the specific projects pages and instead just refer with a one liner to their documentations sites. Those could live under RTD and thus be hooked as child-project directly into https://docs.openradarscience.org or just referenced via link. That would keep us from maintaining the different package pages (and we all know how fast they age).

The overall process might look a bit complex, but it isn't. The very nice thing is, that the different packages can just maintain it's documentation on their own. RTD will do the magic.

Extra sweet is the search function on https://docs.openradarscience.org. It can access the indices of all child projects. So users would just find all related things in the different packages with just one search.

[scollis]

Any news on Discorce @kmuehlbauer ?

[kmuehlbauer]

@scollis No unfortunately not. I've sent a follow up mail on friday, since we had this change in the website which also changed some paths, so that they are aware of that. Unfortunately no response up to now.

[kmuehlbauer]

I think there might be a better solution.

Current setup:

• openradar/openradar.github.io -> https://openradarscience.org
• openradar/openradar-docs -> https://docs.openradarscience.org
• openradar/xradar -> https://docs.openradarscience.org/projects/xradar

If we would move with openradarscience.org from GH-Pages hosting to Readthedocs hosting, then we could declare openradarscience.org as RTD parent site and any other project site (eg xradar) as sub project. This would then look like:

• openradar/openradar.github.io -> https://openradarscience.org
• openradar/xradar -> https://openradarscience.org/projects/xradar

With this we would have anything under only one domain, which in turn is much better for SEO and the like. I'll let this sit now and like to get some feedback. Please let me know, if and how we should tackle this. Thanks!

[kmuehlbauer]

@mgrover1 @scollis Would a dev meeting help here to find a neat solution? Is the pyart dev call today?

[scollis]

The meeting is today! (I can not make it alas) We need to schedule a better time for you CET folks

[kmuehlbauer]

@scollis I'll try to attend, but can't promise.

[mgrover1]

Yeah - let's meet today (mainly just updates from ERAD), and for the next meeting in a couple of weeks, move to a more Euro-friendly time (morning here in the US, afternoon for ya'll)

[kmuehlbauer]

As discussed at the Py-ART dev meeting it turnes out that having everything under one domain (openradarscience.org) is what we should aim for.

@mgrover1 showcased the index search through child projects from the main site, very impressive.

[kmuehlbauer]

In #9 I've enabled the ReadTheDocs build for the site. Now we would need to think about the ramifications if we switch the domain from GH pages hosting to RTD hosting.

The most significant problem which arises is that repos under https://github.com/openradar which use gh-pages won't be available any more under their known and advertised urls.

• Example:

  • Repo: https://github.com/openradar/PyDDA
  • Docs: https://openradarscience.org/PyDDA/

• Other Projects which are affected:

  • https://github.com/openradar/HighIQ
  • https://github.com/openradar/TINT
  • short courses and workshops

1. Simple Solution for documentation

   • projects just move to RTD too as child project of https://github.com/openradar/openradar.github.io
   • eg. PyDDA would be available under https://openradarscience.org/projects/PyDDA/
   • within RTD a redirect https://openradarscience.org/PyDDA/ --> https://openradarscience.org/projects/PyDDA/ can be established

2. Complex Solution for Workshop/Shortcourse Documentation

   • In complex scenarios where heavy computation is involved (and/or docker is involved) we might have to use a precompiled version and override the rtd build process. We would need to trigger rtd after deploying the documentation to GH-pages and pull the precompiled docs into rtd.
   • another idea is to use a subdomain, like https://course.openradarscience.org which is GH-pages hosted, but that would break the nice search feature.
   • keep these projects on GH Pages and just link them (eg. https://openradar.github.io/erad2022/), but that would break the nice search feature too.

@mgrover1 @scollis @rcjackson @zssherman This might need a bit of thought, so no immediate action necessary.