Junit5: Add favicons to the users guide and javadocs web sites

[smoyer64]

Overview

For those of us who always have a lot of tabs open in their browsers, it would make it much easier to get back to the JUnit 5 reference materials.

Deliverables

• [x] Add a favicon to the users guide.
• [x] Add a favicon to the javadocs.

[marcphilipp]

Makes sense! Could be achieved by placing a favicon.ico at the root of junit.org (and overriding it for the JUnit 4 website).

[Andrei94]

I would like to take this one, but I don't know how the websites are generated. Are they from ASCII files?

[sbrannen]

@Andrei94, the Web site is in the gh-pages branch.

Assets such as a favicon image would be stored in the /assets/img folder.

[marcphilipp]

The gh-pages branch only generates the junit5 directory in junit.org/junit5. A root favicon.ico would have to be placed in https://github.com/junit-team/junit-team.github.io.

[sbrannen]

Ahhh... good catch!

[Andrei94]

So the gh-pages for JUnit5 only updates the JUnit5 web site and the Future JUnit Website will update both JUnit5 and JUnit4?

I think then it would be better to update only the Future JUnit Website in order not to duplicate. Also, does the default icon work for junit5? For JUnit4, I was thinking of using this.

[marcphilipp]

In the long, I want to merge both sites. For now, all three repos together comprise junit.org.

We should use the JUnit 5 logo only for JUnit 5 pages (Landing Page, User Guide, Javadoc). We don't need a JUnit 4 icon, unless we need it to override a default one. But overriding may be not as easy, particularly for the old Javadoc.

[Andrei94]

Is the provided image good or should I generate a .ico file from it? As far as I know the ico version has better browser compatibility?

By the way, I am not sure what to do with the Future JUnit website. As far as I saw, it is pretty empty. Could you give me some hints?

[marcphilipp]

Is the provided image good or should I generate a .ico file from it? As far as I know the ico version has better browser compatibility?

I'm not really concerned with compatibility too much. I'll let you figure out the details. 🙂

The landing page already uses it:

<link rel="icon" type="image/png" href="/junit5/assets/img/junit5-logo.png">

By the way, I am not sure what to do with the Future JUnit website. As far as I saw, it is pretty empty. Could you give me some hints?

Yes, right now it consists mostly of redirects. You can pretty much ignore it for now.

[Andrei94]

PR 798

[marcphilipp]

The User Guide is generated using AsciiDoctor: https://github.com/junit-team/junit5/tree/master/documentation/src/docs/asciidoc

[Andrei94]

Do you have problems running the asciidoctor task? I keep getting the rouge gem not installed error, although i did run gem install rouge. I am on Windows, by the way.

[jbduncan]

Interestingly, I get the same problem on my machine.

Both gradle.bat :documentation:asciidoctor in cmd.exe and ./gradlew :documentation:asciidoctor in Cygwin give me the following trace:

:documentation:asciidoctor(RuntimeError) asciidoctor: FAILED: required gem 'rouge' is not installed. Processing aborted.
 FAILED

FAILURE: Build failed with an exception.

* What went wrong:
Execution failed for task ':documentation:asciidoctor'.
> Error running Asciidoctor

* Try:
Run with --stacktrace option to get the stack trace. Run with --info or --debug option to get more log output.

BUILD FAILED

Total time: 24.746 secs

My ./gradlew version is as follows.

------------------------------------------------------------
Gradle 3.5
------------------------------------------------------------

Build time:   2017-04-10 13:37:25 UTC
Revision:     b762622a185d59ce0cfc9cbc6ab5dd22469e18a6

Groovy:       2.4.10
Ant:          Apache Ant(TM) version 1.9.6 compiled on June 29 2015
JVM:          1.8.0_121 (Oracle Corporation 25.121-b13)
OS:           Windows 7 6.1 amd64

[Andrei94]

@jbduncan I found in the meantime a "solution": leave only html5 from backends 'html5', 'pdf' // , 'epub3' in documentation.gradle. It's not something which will work in the long run, but it might help for now 😄

[Andrei94]

@marcphilipp shouldn't the link to the image be placed in head.html? I saw that you did something similar with the favicon from the landing page.

Also, is there a way to test the output of AsciiDoctor locally?

[marcphilipp]

Do you have problems running the asciidoctor task? I keep getting the rouge gem not installed error, although i did run gem install rouge. I am on Windows, by the way.

Hmm, works on my Mac and on Jenkins (Linux). Maybe a Windows issue? Please open a separate issue for it.

shouldn't the link to the image be placed in head.html? I saw that you did something similar with the favicon from the landing page.

No, head.html is only used for Jekyll-generated HTML pages. Instead, you need to configure AsciiDoctor as described in https://github.com/asciidoctor/asciidoctor/issues/1574#issuecomment-156698241.

Also, is there a way to test the output of AsciiDoctor locally?

Yep, just run ./gradlew asciidoctor and look at documentation/build/asciidoc/index.html.

[Andrei94]

Hmm, works on my Mac and on Jenkins (Linux). Maybe a Windows issue? Please open a separate issue for it.

Could be a Windows issue. The problem with the gem also appears with the spring repository. I had to make a local hack there as well. 😄

[Andrei94]

Are there any possibilities to leave the index.html page from javadocs? By leaving, I mean to have for example http://..../docs/current/api/AfterEach.html? As far as I understand, the official Java documentation also uses AsciiDoctor and there are cases over there.

[sbrannen]

For those interested in the Rouge issue on MS Windows, please see #799 and https://github.com/asciidoctor/asciidoctor/issues/1040.

[sbrannen]

@Andrei94

Could be a Windows issue. The problem with the gem also appears with the spring repository. I had to make a local hack there as well. 😄

Did you raise an issue in Spring's JIRA issue tracker?

If not, could you please do so?

Thanks,

Sam (the guy who switched Spring's build to use Rouge)

[Andrei94]

Did you raise an issue in Spring's JIRA issue tracker?
If not, could you please do so?

@sbrannen Done SPR-15471

[sbrannen]

@sbrannen Done SPR-15471

Thanks. Much appreciated!

[sbrannen]

FYI: in case you're not following the related issues... due to a bug in Rouge that prevents its usage on MS Windows (https://github.com/jneen/rouge/issues/661), we will be switching to coderay for the PDF version of the User Guide for the time being.

[Andrei94]

@marcphilipp PR 802