search

SuperDARN / rst

Radar Software Toolkit (RST)
https://superdarn.github.io/rst/
GNU General Public License v3.0
22 stars 18 forks source link

Removing the RFC documentation #532

Open ecbland opened 1 year ago

ecbland commented 1 year ago

DEPRECATION

We had planned to remove the RFC documentation from the RST after migrating the content to readthedocs in #377.

https://github.com/SuperDARN/rst/blob/c48c5c3e2ae258905c320ece81d5973387af66d4/build/doc/sk/rfc.inx.local.sk#L24-L32

It would be nice to do this for the RST5.0 release, but please chime in if there's a good reason to keep it a bit longer. I had a quick look at the code and it seems fairly simple to remove. (see also #47 when the RFC documentation was added)

While looking at the code I also noticed a script for building tutorial documentation, make.doc.tutorial, but I'm not sure where the source code is. Do these tutorials exist?

egthomas commented 1 year ago

@ecbland a snapshot of the old tutorials can be found here:

https://web.archive.org/web/20050908143338/http://superdarn.jhuapl.edu/devel/tutorial/index.html

I used that information to populate the tutorials on the wiki page several years ago (e.g., https://github.com/SuperDARN/rst/wiki/Working-With-Data).

I would not be in favor of removing the RFC documentation from the RST, but admit I am probably in the minority on that front.

pasha-ponomarenko commented 1 year ago

@ecbland, I don't have any strong opinion on this, but if this information is either redundant or outdated, then it makes sense to remove it from RST and to archive somewhere on this repository.

mtwalach commented 1 year ago

Personally, I do use the RFC docs occasionally and I do like having them though I appreciate they are perhaps not very accessible and I don't have a good reason either (other than, I occasionally use them but it's probably just Evan and I).

ksterne commented 1 year ago

Interesting to hear that there's still usage of these since I'm not sure how up-to-date they are! Is it helpful or possible to use our readthedocs site (https://radar-software-toolkit-rst.readthedocs.io/en/latest/)? I think I'm mostly asking @egthomas and @mtwalach so far. When we discussed this a bit ago, we figured moving all of the documentation to a central location would be beneficial.

ecbland commented 1 year ago

Thanks for the input on this discussion. I don't want this to hold up making the release branch, since we have 1 month of testing ahead of us. If we land on a decision during that testing then we can make the changes on the release branch. I'll leave this issue open so that it stays on our WG's agenda.