search

jython / jython

Python for the Java Platform
https://www.jython.org
Other
1.14k stars 185 forks source link

Delete outdated legacy website files #333

Closed meenbeese closed 6 days ago

meenbeese commented 3 weeks ago

These files are now unused and outdated as the Jython website is currently handled in its own repo.

Also shaves off quite a few kilobytes from the project, 94.04 KB to be precise.

Closes #180

Stewori commented 3 weeks ago

I have been looking at those files and I don't think it is a legacy website, but it is actually an early version of the user guide. Note that these files are actually on display on APIdia. That is, because APIdia mimics the behavior of Javadoc to include files from a doc folder (although .ht support is an extra). (The Java standard lib uses doc folders for additional documentation on several occasions, which is why I think that Jython's doc folder was meant to enhance Javadoc). Okay, you might notice that the files in APIdia have updated links and the hopelessly obsolete ones like jythonc have been removed. That is because I polished them such that the remaining content is applicable to current Jython. (I am going to make a PR for that - it is on my todo-list, just had other stuff to do...) So, that work appears to conflict with this removal approach. That being said, I intended the cleanup only as an intermediate solution because the user guide itself, also the "actual current" one, really needs cleanup:

There are several competing versions: https://wiki.python.org/jython/UsersGuide (is a non-existing page which causes the wiki to list the various userguide instances as suggestions of similar pages) There exist at least

My plan is to merge them into one authoritative version, and find some way to have one single source from which a user guide can be provided in the wiki (perhaps better remove it from the wiki, actually), on the homepage, and on APIdia. However, that is more like a long term plan, which I might be able to carry out later this year.

On short term, I am going to file the promised PR for the polished doc folder, even in time for 2.7.4 release (it's not really relevant for the release, but anyway).

Stewori commented 3 weeks ago

Okay, I re-read Franks comment https://github.com/jython/jython/issues/180#issuecomment-1188444751 and it is apparently an early version of a website. However, at the same time it is factually an early (or just reduced) version of the user guide and I do not see what is wrong with the docs after polishing, which was really just removing some obsolete stuff and updating links. The cite "really much better documentation" must be seen in context of the current user guide, which is some enhancement of the Doc folder but does contain most of it literally. So, the cleanup I did on the Doc folder should be applied to the user guide as well, but that will be part of the more general cleanup plan described earlier.

I checked the Javadoc-doc and would adjust the doc folder, when making a PR with the polished docs such that it complies with the description https://docs.oracle.com/javase/7/docs/technotes/tools/solaris/javadoc.html#unprocessed (sorry, just found the Java 7 link, but I know that current Java still uses that structure).

Stewori commented 3 weeks ago

Okay, there it is: #334

meenbeese commented 6 days ago

Thank you for the PR. Sorry, as I was quite busy for the past few weeks and could not find the time to properly respond. So, as I understand it, do you still see enough value in the user docs to let them live alongside the website that we currently have? I didn't know that this APIdia existed, but it looks like an interesting and useful website. Should I make a PR to add this to the README here or to the website? If you are making a lot of effort to revive this old documentation, we might as well make it more accessible to the users of Jython's API in a bid to increase the documentation here. I can also help with that PR of yours later this year if you describe, maybe in a separate issue, which sources will be removed, reorganized, and merged into the current ones.

In the meantime, should I close this current PR?

Stewori commented 6 days ago

you still see enough value in the user docs to let them live alongside the website that we currently have?

Whatever the answer would be, it would apply to the user guide as well since there is not so much difference. In that light, the answer is easier: a user guide is certainly a good thing to have. But you are right, the discussion about sanitizing the user guide should take place somewhere else, i.e. as a separate issue or on the mailing list.

I didn't know that this APIdia existed, but it looks like an interesting and useful website.

I'm glad you like it! For some background, check out my announcement I see, you are an Android dev (sorry that Jython still lacks the support). Android standard library is not on APIdia yet -- working on it :)

we might as well make it more accessible to the users of Jython's API

Yes, in sense of the user guide. I agree that the user guide should be moved from the wiki to the website, however I would like to keep it on APIdia as well. I still wonder what is the best way to achieve that with a single source. However, that's a separate discussion. For now I suggest to close this PR in favor of my PR with the polished docs.

I can also help with that PR of yours later this year if you describe, maybe in a separate issue, which sources will be removed, reorganized, and merged into the current ones.

Sure, that sounds great. I already downloaded the sources of the competing user guide wiki pages listed earlier in this thread. I diffed them to understand the differences. If you like to participate on that issue, open it on the tracker and I will share what I have so far.

meenbeese commented 6 days ago

Thank you for the detailed reply. I closed the PR and opened #338.