Issue2658

classification
Title: Update jython.org website
Type: behaviour Severity: urgent
Components: Documentation, website Versions: Jython 2.7
Milestone: Jython 2.7.2
process
Status: open Resolution: accepted
Dependencies: Superseder:
Assigned To: jamesmudd Nosy List: adamburke, amak, fwierzbicki, jamesmudd, jeff.allen, stefan.richthofer, zyasoft
Priority: high Keywords:

Created on 2018-03-26.21:42:02 by jeff.allen, last changed 2018-11-28.18:19:09 by jamesmudd.

Messages
msg11855 (view) Author: Jeff Allen (jeff.allen) Date: 2018-03-26.21:42:00
The website is out of date and does not link the latest distribution or documentation. (See also #1590.) We need jython.org to present up-to-date information to support the 2.7.2 release, from the availability of the beta release. Even a simplified site is better if it is up-to-date.

We would like to move management of the website source to GitHub, which will allow us to share updating it.

See discussions on the jython-dev list (e.g. https://sourceforge.net/p/jython/mailman/message/36238580/). I'm raising an issue to signal that we regard this as part of the 2.7.2 release, as important as any software fix.
msg11866 (view) Author: Stefan Richthofer (stefan.richthofer) Date: 2018-04-01.15:11:13
Just wanted to point out (yet again) that the sphinx rst-source code of the website is available via links at the bottom of the website itself.

I would suggest a migration path based on existing source rather than writing a new website from scratch. Can't we just host the rst-source on github? IIRC read the docs is compatible with sphinx rst. Alternatively we could try e.g. pandoc to turn it into markdown for github pages, which does not directly accept rst AFAIK.
Main effort would be to have an easy build and update mechanism. Does read the docs support some automated process here?
msg11922 (view) Author: Stefan Richthofer (stefan.richthofer) Date: 2018-04-25.17:25:00
Backlinking #2671 here as another manifestation of outdated website issue.
msg12095 (view) Author: James Mudd (jamesmudd) Date: 2018-09-08.16:58:38
I'm hoping to get some time to look at this over the next few weeks and just wanted to check the status. 

I'm assuming the idea is to move the website to Github pages at https://jython.github.io/ ? Using the repo https://github.com/jython/jython.github.io ?

Is the first idea to start migrating the existing content from the jython.org site there? That was where I was thinking of starting.

Has anyone else already worked on this?
msg12096 (view) Author: Jeff Allen (jeff.allen) Date: 2018-09-08.18:03:51
That would be great. Nothing started AFAIK.

I believe it would be possible to dress a jython.github.io site as jython.org when we are ready, and with the help of the PSF infrastructure team who own the name.

The front page text is available at the link but the frame and navigation are something separate. I think Frank would know what, if you want to re-use it.

I like Sphinx for documents and have used it succesfully with readthedocs, but it produces something more like a book. GitHub itself will try to render RST but only supports a subset of Sphinx RST. See for example https://github.com/jython/devguide/blob/master/committing_hg_jy.rst .

Most of the content is a link out to the Wiki, PSF or documentation that could well be Sphinx and could be at RTD. The actual site need be very few pages, maybe one. The PyInstaller site might be a good example, or the ANTLR one. (ANTLR do their docs with GitHub Markdown but it's not the website, and is a bit constraining.)
msg12097 (view) Author: Stefan Richthofer (stefan.richthofer) Date: 2018-09-08.21:42:02
Just wanted to point out that the source of python.org is also available online at https://github.com/python/pythondotorg.
I personally find that python.org looks rather professional, especially compared to a sphinx page. Anyway, it is probably too much work to fork that into a jython.org. Also, since it is django-based it certainly puts a higher demand on the webserver. Still it might be a good source for looking up one or the other code or text snippet.
msg12100 (view) Author: James Mudd (jamesmudd) Date: 2018-09-11.20:15:41
I have been playing with this for a few days and this is what I have so far https://jamesmudd.github.io/jython.github.io/ with the source here https://github.com/jamesmudd/jython.github.io

Its using Github markdown for the content, with some custom html for the navigation which can be customized via the https://github.com/jamesmudd/jython.github.io/blob/master/_data/samplelist.yml file (which should probably be renamed)

Just curious for people to have a look and see if its the right kind of direction? Hoping it would be easy to edit and maybe more more documentation etc there in the future? There are a few minor rendering bugs a the moment but it generally works on all browsers including mobile.
msg12101 (view) Author: Jeff Allen (jeff.allen) Date: 2018-09-12.06:47:45
Nice work! That looks good. Markdown is less limiting than I expected.


Front page:

I like "what is" as a front page better than News, especially as news is somewhat slow.

We should signal our PSF allegiance clearly. Certainly with links into python.org.

We've often said we should have a "who uses Jython" section: other projects/products that make serious use. It's in IBM WebSphere, Pig and RobotFramework for example. Maybe there's a prestigeous research institition too.

I expected "view on GitHub" to take me to the source of the website.

I found "Jython maintained by jamesmudd" a little odd. Maybe this is generated. I think the link here should be who maintains the website, and in any case, we could take responsibility as a team.


Documentation:

Good. I think the main issue is how to provide JavaDoc. One approach might be to link a JAR on Maven Central (the Gradle build supplies one) but that's more like a download. But it's useful, I think, if it can be browsed directly (and is found by search engines), but where? It would be a pain to check the tree in to the repo. Maybe not such a pain: it's only done after a release, so that would be sub-annually.

This is a better link for the devguide: https://jython-devguide.readthedocs.io/en/latest/ 

The Very Slow Jython Project is probably only of interest to folk like us.
msg12102 (view) Author: Stefan Richthofer (stefan.richthofer) Date: 2018-09-12.08:39:42
For Jython's javadoc, javadoc.io could be a simple solution for now. They seem to update javadoc for all sorts of projects from time to time: http://www.javadoc.io/doc/org.python/jython-standalone/2.7.1

In the long run, we should however host an "official" javadoc build.

I think the very slow Jython project is an interesting read for potential new contributers and don't see why it shouldn't be linked somewhere.
msg12103 (view) Author: James Mudd (jamesmudd) Date: 2018-09-12.17:06:14
Thanks for taking a look, I'm quite pleased with how its going.

Thanks for the suggestions, here are some comments.
- I have updated the dev-guide link.
- I have removed the maintained by footer that was a auto-generated part of the theme i'm using, not sure how useful it would be even if it was correct though, so removed.
- Changed the JavaDoc link to javadoc.io. I think hosting it here in the future would be a good idea though so I will look into that.

I will do some more on the home page I think a "who uses" section would be good and can try some more advanced markdown.

I think a getting started guide would be good too so I might have a look at that.

For the "Very Slow Jython Project" link I think its useful but maybe not under Documentation. I was thinking of having a links page to collect together more stuff like this, and a place for Jython related projects like JyNI.
msg12104 (view) Author: Stefan Richthofer (stefan.richthofer) Date: 2018-09-13.12:44:11
I noticed that in your javadoc all packages with names of the form "org.python.modules._xy" cause 404. Same for the classes within.
Does a leading "_" somehow cause problems for javadoc? At http://www.javadoc.io/doc/org.python/jython-standalone/2.7.1 these classes seem to work, it must be doable somehow.
msg12131 (view) Author: Stefan Richthofer (stefan.richthofer) Date: 2018-10-09.06:38:02
I'm following up on the email thread "[Jython-dev] What's needed to get jython.org updated?", see https://sourceforge.net/p/jython/mailman/message/36435980/. I share Jim's view that James' work should get online ASAP. IMO it is right now already much better suited as a Jython homepage than current jython.org. Some remarks:

- I discovered that traditionally, old Jython websites are still archived: http://www.jython.org/oldsites.html
We should keep this habit and preserve current jython.org in some way. I think that jython.org has some direct server url under the hood. Can we redirect jython.org and place an "oldside" link to the original webspace on the new page? Otherwise we'd have to look into tools for website cloning to preserve a copy of current jython.org.

- @jamesmudd I noticed that https://github.com/jamesmudd/jython.github.io does not allow to create issues. (I wanted to file issues on some typos) Anyway, the best solution would be to push your work back to https://github.com/jython/jython.github.io. Could you do that soon?

- One thing occurred to me about the logo: On jython.org (and also on https://jamesmudd.github.io/jython.github.io/index) the logo is fairly low quality. There are better quality versions floating around in the internet, e.g. at https://smartbear.com/blog/test-and-monitor/embedding-jython-in-java-applications/. I don't know where the author originally found the higher quality version of the logo; I wasn't able to spot it anywhere on jython.org. Can we simply take the one linked above? It's still the original logo, just in higher resolution and should thus be PSF-owned. Opinions?

@zyasoft Jim, what needs to be done to redirect jython.org to https://jython.github.io/jython.github.io/index? It is under PSF ownership, isn't it? Who needs to be contacted?
msg12132 (view) Author: James Mudd (jamesmudd) Date: 2018-10-09.07:09:56
Thanks for the comments. I agree that its already "good enough" to work as a replacement and once its there anyone can start contributing to it.
I wanted to move the "new website info" to the News page. so I will do that and then open a PR to update https://github.com/jython/jython.github.io.
I don't think I can push there directly? I haven't tried though.

@Stefan You raise a few points I had also been considering.
1. Keeping the old website accessible somewhere. I haven't looked at this. Should it be part of the new site or hosted somewhere else with a link? Definitely think this should be done. I think it would work if I copy all the HTML in I will have a look at that too.
2. Higher resolution logo. I was meaning to ask about this do we have a vector version of the logo I could use?

On the JavaDoc issue. I have changed back to javadoc.io for now, which might even be a better option. However the issue is that _ is used for special files/directories in Jekyll see https://help.github.com/articles/files-that-start-with-an-underscore-are-missing/ there are a few workarounds which I tried but didn't get any of them to work nicely. I got it to work but additional files I didn't want were copied. Would be worth some more investigation if we decide we want to host JavaDoc.
msg12133 (view) Author: Stefan Richthofer (stefan.richthofer) Date: 2018-10-09.08:56:03
> I don't think I can push there directly? I haven't tried though.
I think you can't at the moment, but that definitely shall be made possible. Will follow up on this aspect via email...


> 1. Keeping the old website accessible somewhere...

I am fine with whatever option is technically easier. I would find it nice if we could have a menu entry to access old sites like http://www.jython.org/oldsites.html, listing 2.5/2.7 site along with its ancestors 2.1, 2.2.


> 2. Higher resolution logo. I was meaning to ask about this do we have a vector version of the logo I could use?

I once asked a question like this on the mailing list and failed to get an answer. Just searched again and found this thread https://sourceforge.net/p/jython/mailman/message/8857981/, leading to https://jesseross.com/clients/jython/index.html. That seems to be the original source and contains no svg. If we really require an svg we could seek contact to Jesse Ross and ask if he still has the svg source that was apparently used to create the varying formats on that page linked. Alternatively we could use a tool like portrace (nowadays included with inkscape by default). However, I think the high resolution version at https://jesseross.com/clients/jython/index.html is sufficient for now.


> On the JavaDoc issue. I have changed back to javadoc.io for now...

javadoc.io works well enough and there are more important issues than self-hosting javadoc. Let's go with javadoc.io for a while and see how reliable it is. E.g. let's see how long it takes to mirror javadoc of Jython 2.7.2 when it is released.
msg12134 (view) Author: James Mudd (jamesmudd) Date: 2018-10-11.10:10:38
A quick update.

Think I have cleaned up the site a bit more, moving to higher res logo, adding page titles etc and it could not be merged. I have opened a PR https://github.com/jython/jython.github.io/pull/3 to do that. I still can't push directly to the Jython organisation. I think I can to jythonTools (but i haven't tried it, I just see I could merge PRs)

On keeping the old website: Initially I added it to the new site but I didn't really like it as it made the repo very large as it contains podcasts etc. So I stripped the biggest stuff out but it was still quite large ~40 MB and now had some of the content missing. Then I had a better idea, make another repo to hold the archived site content, and host that using Github pages too. So this is now available at https://jamesmudd.github.io/jython-old-sites/ with the repo here https://github.com/jamesmudd/jython-old-sites this would need to be transferred to Jython ownership or an equivalent repo made there, once its working it can be marked read-only on GitHub as it should never change. The current new site needs to have links back to the archived site, currently this point at the actual jython.org site but those can easily be changed.

I think this approach of having a separate repo might work nicely for hosting JavaDoc too so I will take a look at that.
msg12188 (view) Author: James Mudd (jamesmudd) Date: 2018-11-28.18:19:09
Just wanted to bump this back up.

The new site is now available at https://jython.github.io/

The remaining task is to point the jython.org domain to this site I understand some issues were encountered doing this?

There are then a few open issues and PRs to improve the site further. I would like to merge but I don't have permissions to merge into this repo.
History
Date User Action Args
2018-11-28 18:19:09jamesmuddsetmessages: + msg12188
2018-10-12 08:12:26jamesmuddsetassignee: jamesmudd
2018-10-11 10:10:39jamesmuddsetmessages: + msg12134
2018-10-09 08:56:04stefan.richthofersetmessages: + msg12133
2018-10-09 07:09:57jamesmuddsetmessages: + msg12132
2018-10-09 06:38:04stefan.richthofersetnosy: + zyasoft, adamburke
type: behaviour
resolution: accepted
messages: + msg12131
severity: normal -> urgent
2018-09-13 12:44:12stefan.richthofersetmessages: + msg12104
2018-09-12 17:06:14jamesmuddsetmessages: + msg12103
2018-09-12 08:39:42stefan.richthofersetmessages: + msg12102
2018-09-12 06:47:46jeff.allensetmessages: + msg12101
2018-09-11 20:15:42jamesmuddsetmessages: + msg12100
2018-09-08 21:42:02stefan.richthofersetmessages: + msg12097
2018-09-08 18:03:51jeff.allensetmessages: + msg12096
2018-09-08 16:58:38jamesmuddsetnosy: + jamesmudd
messages: + msg12095
2018-08-01 17:15:23amaksetnosy: + amak
2018-04-25 17:25:00stefan.richthofersetmessages: + msg11922
2018-04-01 15:11:13stefan.richthofersetnosy: + stefan.richthofer
messages: + msg11866
2018-03-26 21:42:02jeff.allencreate