Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

documentation for openradar projects #6

Open
3 tasks done
kmuehlbauer opened this issue Sep 5, 2022 · 12 comments
Open
3 tasks done

documentation for openradar projects #6

kmuehlbauer opened this issue Sep 5, 2022 · 12 comments

Comments

@kmuehlbauer
Copy link
Contributor

kmuehlbauer commented Sep 5, 2022

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:

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

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
Copy link
Contributor Author

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
Copy link
Contributor Author

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
Copy link
Contributor Author

@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
Copy link

scollis commented Sep 6, 2022

Any news on Discorce @kmuehlbauer ?

@kmuehlbauer
Copy link
Contributor Author

@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
Copy link
Contributor Author

I think there might be a better solution.

Current setup:

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:

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
Copy link
Contributor Author

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

@scollis
Copy link

scollis commented Sep 13, 2022

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

@kmuehlbauer
Copy link
Contributor Author

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

@mgrover1
Copy link
Contributor

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
Copy link
Contributor Author

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
Copy link
Contributor Author

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.

  1. Simple Solution for documentation

  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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

3 participants