Issue2658

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.

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?

Backlinking #2671 here as another manifestation of outdated website issue.

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?

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.)

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.

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.

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.

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.

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.

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.

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?

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.

> 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.

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.

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.

We have a basic website we like (https://jython.github.io/), essentially thanks to James. We would like it to appear as (www.)jython.org.

I found this guidance which might explain what we have to do to get the website live: https://help.github.com/articles/setting-up-a-www-subdomain/#configuring-a-cname-record-with-your-dns-provider .

There are several blogs about doing this:
http://jmcglone.com/guides/github-pages/
https://blog.teamtreehouse.com/using-github-pages-to-host-your-website
although it is hard to know always whether such writing is up to date. Generally the message seems to be that this is not difficult.

Can anyone give an account of what has been tried? All I know is that somebody tried something and it failed.

> Can anyone give an account of what has been tried? All I know is that somebody tried something and it failed.

I can do up to my knowledge.

There was this email-thread:
https://sourceforge.net/p/jython/mailman/message/36454948/

We followed up a little bit privately where Frank stated
"... I had hoped just changing the CNAME would be enough, but it wasn't - the github page just showed an error. I need to go through the github docs and figure out what else needs to be done. I might be able to try again this weekend."
(Editorial note: "this weekend" refers to mid of December 2018)

I pointed out https://help.github.com/articles/quick-start-setting-up-a-custom-domain as a starting point.

Apparently it wasn't so easy or Frank was blocked otherwise.

@Frank Any updates on this?

Until jython.org is redirected we could at least replace the homepage link in the header of https://github.com/jythontools/jython
by https://jython.github.io

Thoughts?

I'll see if I can give the redirect another try this weekend. In the meantime, I think replacing the homepage link in the header of https://github.com/jythontools/jython
with https://jython.github.io sounds like a good idea.

That would be great, Frank. Good idea, and done. We'll move it back when you succeed, so I don't propose to change it anywhere else.

I think it takes 2 things for that to work.
1. Someone looking for subdomain www.jython.org ends up at GitHub's page server.
2. GitHub knows that someone arriving and asking for www.jython.org should be shown our site.

The first is the business of the A records in DNS, which the PSF infrastructure team control, because they own the name. (Possibly needs a CNAME in DNS too.) The second is accomplished by writing www.jython.org in a file called CNAME in the web site repo. At least, that's what I think I know.

Even if I'm right, I've a question in my mind about HTTPS. What makes a browser that visits www.jython.org (and ends up on GitHub's server) believe that the site is genuine? In other words, where does the certificate go? (Does GitHub generate one?)

The logo is also on our Wiki: https://wiki.python.org/jython/JythonLogo, but I think Stefan has found the artist.

Jeff

I did an experiment to see if I've understood how this is supposed to work. I forked the repo https://github.com/jython/jython.github.io, which James worked so hard on, and made it my own as https://github.com/jeff5/jeff5.github.io . This was enough to make it appear as a personal site at https://jeff5.github.io.

I then set up the DNS zone file (at my provider) for a domain name I own to point @ and www to the IP addresses GitHub specify. As a result, the Jython website is now visible as http://farowl.uk . It took about an hour hor my local DNS to catch up with the address change.

It took another 12 hours for GitHub to make me an SSL certificate, but now it's also at https://farowl.uk . I found it interesting that this was both free and automatic.

I don't know if the infrastructure team tried this for us before (with jython.org) and it failed, or tried something else. However, this was pretty painless and has worked.
https://help.github.com/en/articles/setting-up-an-apex-domain-and-www-subdomain

The GitHub help on this seems clearer now than I remember it.

Think this can now be marked ad done! Thanks to everyone who helped to get this finished!