JSqlParser - website discussion

[sivaraam]

Let's create a website for the library! This issue is to track the discussion related to the website creation.

[sivaraam]

Jekyll template suggested by @wumpz: Minimal Mistakes

[sivaraam]

@wumpz For the sake of completeness, can you list the information that you wish the website should provide to its visitors?

[wumpz]

Let me think about it:

• quickstart (maven, gradle)
• introduction visitor pattern
• introduction object tree of jsqlparser
• common tasks: parsing, replacing, analyzing
• examples

I think the biggest gap is explaining jsqlparsers object tree. Much of this should go into the javadocs as well.

[sivaraam]

That looks like a good start! I think it would also be nice to add a link to the javadocs.

Anyways, I'll set up an initial webpage based on the Minimal Mistakes template and then we'll add more content to it.

In the mean time, if you would like to host the site at https://jsqlparser.github.io/ instead of https://jsqlparser.github.io/jsqlparser you would have to create a repository in the JSQLParser organization with the name "jsqlparser.github.io" (reference)

[sivaraam]

Hi @wumpz,

Sorry I couldn't get the initial site past weekend. Anyways, I've started looking into it now.

Just wanted to ask you something. Though I initially told the Minimal Mistakes theme was nice. On second thought, it seems to give a dull kind of appearance to the website. So, I think its better to go with some other theme which gives a more appealing look. Let me know your opinion.

If you also agree on choosing an alternative theme, let me know your opinions about the one of these alternatives (or) suggest other ones.

• Hyde
• Beautiful Jekyll

[wumpz]

Beautiful Jekyl looks nice as well. But Minimal Mistakes is kind of a framework. Beautiful Jekyl as well?

[sivaraam]

But Minimal Mistakes is kind of a framework.

I'm not sure what you mean by a framework here. But on taking a closer look, minimal mistakes does look like a more mature and widely used template when compared to beautiful jekyll. So, we can just go with Minimal mistakes if you are fine with it.

The minimal mistakes template does provide some skin variants at our disposal. Let me know your opinion about which one to choose. You can find them in the following link: https://github.com/mmistakes/minimal-mistakes/blob/master/README.md#skins-color-variations

[wumpz]

At first look I would say: air, mint, contrast are my favourites. However this skinning is done using some options, so changeable afterwards.

[AnEmortalKid]

+1 for contrast

[manticore-projects]

@wumpz: From our discussion, I take that you agree we need a website. I face the same challenge for my own project JSQLFormatter, so maybe we can kill two birds with one stone.

I did some research and conclude: 1) "maintenance" will be the biggest challenge. For this reason I am looking for a Maven (or Gradle) based solution in order to build/refresh the website after every release. 2) HTML5 and Mobile Devices should be supported (SEO) 3) Lightweight static website, with as little as possible Javascript and other assets 4) Simplified language would be great (I do not want to write plain HTML/CSS myself), but the language should scale beyond the Markdown capabilities.

The best match I found was [Sphinx Documentation[(https://www.sphinx-doc.org/en/master/index.html). It has Maven plugins (or Gradle), supports a more powerful Markdown alike language and generates good HTML5 output (but also other formats). Furthermore it showcases some light and clean Templates, e.g. enthought.

The biggest caveat is: It's PYTHON based, but I think as long as this is well hidden by the Maven Plugin this does not hurt too much. I am using Linux only and so Python is always there even when I never use it directly. Also, GraalVM supports Python.

Long story short: please let me know what you think and any objections. In the best case I would set up such a Sphinx based website for JSQLFormatter, fill it with minimal content and show-case it to you. If you like it, we just duplicate everything for JSQLParser.

If you had any serious concerns, I would rather look into a different direction.

[AnEmortalKid]

What about hugo: https://gohugo.io/ or jekyll with github pages?

[manticore-projects]

There seems to be a Maven Hugo Plugin, which publishes directly to github pages: https://sonatype.github.io/dionysus-support/maven-plugin/. It also supports RST (which is the Sphinx language with more capabilities than MarkDown). Plenty of nice themes avalaible as well.

This would be a good alternative! So which way to go please? Hugo with RST because it has more templates, but also would support Sphinx (later, for PDF/printed documentation?)

[manticore-projects]

After a very brief scan of Hugo, I found: 1) all the templates seem to be "fixed width" and won't use the full screen 2) the "table of Contents" capabilities seem to be limited compared to Sphinx 3) there is no integrated search

So in short, it appears to me that Hugo is better for "stylish" and "blogging" while Sphinx looks better for technical documentation. However, that's my own impression. I think, we can make both solutions works and as long as we stick to RST even switch any time later (is that correct?).

[manticore-projects]

Gentlemen, reading and trying out a lot of stuff, I have found out that on technical writing there are two major factions: AsciiDoctor and reStructuredText (rst).

AsciiDoctor seems to be more popular and is supported by Hugo, Antora and Orchids. Hugo has good theming, Antora has no theming but for any reason seems to be popular. Orchids has theming and JavaDoc support, but does not seem to be very matured.

The most interesting thing about AsciiDoctor is the availability of a Java Doclet, which outputs AsciiDoctor (although it does not seem to be maintained well). This has the beautiful advantage that we could publish the Java Doc in the same look and feel like the rest of the documentation and everything under one hood.

reStructuredText and Sphinx seems to be matured. I got it instantly working with Maven and it has great themes. For any reason I love it. Although it is Python based. There is a Plugin for JavaDoc but that is abandoned and I got it working only by hacking some Python files.

So right now I see exactly reasonable Options:

1) Hugo, based on Ascii Doctor with the Ascii Doclet and good theming (although the themes are not as good as the Sphinx' ones). Some of the better/interesting themes also depend on Javascript/NPM. 2) Antora, looks great by default. I hate the fact that it is Javascript/NPM.

3) Sphinx, reStructuredText. Include the Java Doc has it is and write a RST Doclet later?

Should we flip a coin? Best out of five?

[manticore-projects]

I have played a bit more with Sphinx and I think I will go for this. To me, the templates look better and output appears more professional.

More importantly: It calls a Python script during the website building, which you can use to add all kinds of dynamic content and information from your project, e. g.

• POM.xml attributes, like ArtifactID, Author, Dependencies
• Binary files (with size and date)
• GIT changelog

The only gap I have identified so far is the integration of the JavaDoc, but lets face it: JSQLParser would need to work on its JavaDoc first and JSQLFormatter has only one static method format(String... args) to document.

[wumpz]

I am still not convinced, why github pages is not an option. Using Jekyll there are thousands of templates around: http://jekyllthemes.org/, https://jekyllthemes.io/free.

It has its benefits using something, that is already integrated. Creating or integrating javadoc should not be a problem here and with github.io it has already its place. Most of the dynamics you can integrate or have provided by themes.

https://stackshare.io/stackups/jekyll-vs-sphinx

However, I read about integrating sphinx to github pages. What I like, is that sphinx provides multiple output formats. Integration into the maven build sounds good.

All I had to publish, went into githubs wiki, and did a good job as well.

[manticore-projects]

Jekyll is definitely an option! And if you like it, you should go for it, I am not here to evangelize anyone.

For my own project, I chose eventually Sphinx simply because I liked the templates a bit more (it looks more like a traditional doc with TOC, Index, pagination, footnotes) and I like the tool-chain a bit more (everything can be deployed from Maven directly). Last but not least it works independently from GitHub so I can migrate to something else at my own convenience without breaking any tool-chain (Just in case.)

If you are ever interested in copy'n pasting my work on the sphinx integration, let me know. Otherwise I would rather focus on the With... statements and on the SQL Formatting.

Cheers.

[wumpz]

Just wanted to ask. Sure you are much deeper in this topic. At least I used sphinx generated docs from geotools or geoserver and those are doing well. So no complaints here ... If I understand right, sphinx is able to publish to GitHub.io as well. So do you have a template for using this?

[manticore-projects]

Look at this beauty: https://manticore-projects.github.io/jsqlformatter/index.html#

If I understand right, sphinx is able to publish to GitHub.io as well. So do you have a template for using this?

Yes, I have managed to deploy everything from maven with a simple

JAVA_HOME=/usr/lib/jvm/java-11-graalvm mvn clean install site scm-publish:publish-scm

The result looks quite nice and reflects Changlog and Downloads for the Latest Versions without any manual intervention. (Although I must say, the substitution is maybe Sphinx' weakest spot.)

What I like most is: 1) you can directly link samples from the source code, so the documentation will always stay up-to-date even after a refactoring 2) the tabs (e.g. for showing Java vs C++ or Linux vs. Windows)

So how to integrate everything:

1) install Sphinx along with a few extensions, tweak your conf.py file (e.g. the maven properties substitution) 2) create your documentation in $SOURCE_DIR/site 3) create an Orphan Branch (which will be used solely for holding/pushing the compiled documentation to GitHub Pages) 4) activate Github Pages on Git Hub and set it to your orphan branch 5) configure the Maven server.xml with the credentials to your github project/account 6) add some Maven plugins sphinx-maven-plugin (for building the Sphinx documentation), maven-scm-publish-plugin (for publishing to Github using GIT)

Do not use the Github Site plugin! Its garbage! I wasted almost a day with it achieving nothing. Also, you will want to use the local Sphinx over the bundled one (or the extensions won't work reliable).

You can take the templates for conf.py and the pom.xml from my project. Using this should make things easy.

One thing I did not get working yet is the search for my particular Sphinx template.

[gitmotte]

Why not using maven site plugin? The result of generated website will look like the site generated for the site plugin itselve https://maven.apache.org/plugins/maven-site-plugin/

It's format well known in java world - it's result is responsive and simple wiki markup languages are used to generate html - i.e. markdown. see https://maven.apache.org/plugins/maven-site-plugin/examples/creating-content.html

[manticore-projects]

Why not using maven site plugin?

1) Maven 2) Themes 3) Syntax Highlighting of code snippets

Even Apache projects (e. g. Shiro) don't use it, when they want to present content in a nice way. Btw. Shiro has had a similar discussion last year when they switched their own CSM. They conclusion was to best chose the most commonly used CMS with the largest users and developer base. So as far as it concerns me, only Hugo and Sphinx and Jekyll are serious contenders.

[gitmotte]

Why not using maven site plugin?

1. Maven

2. Themes

3. Syntax Highlighting of code snippets

Even Apache projects (e. g. Shiro) don't use it, when they want to present content in a nice way. Btw. Shiro has had a similar discussion last year when they switched their own CSM. They conclusion was to best chose the most commonly used CMS with the largest users and developer base. So as far as it concerns me, only Hugo and Sphinx and Jekyll are serious contenders.

Well, we know you don't like Maven ... the website you created with Sphinx doesn't look much different than websites you can create with Maven. It's just a matter of css styles to make it prettier ...

... but - maven site plugin runs with java, you don't need python.

[wumpz]

To be honest I have no idea how maven sites are prettified. I only use https://maven.apache.org/skins/maven-fluido-skin/. But this is only for company internal stuff. I use AsciiDoctor to create the sites. But to set it up was hard to get all needed plugins running.

[manticore-projects]

In my opinion, when having nothing, then anything is better than that. Secondly, I was hoping that we would discuss content or design/themes, instead of tooling. At this point you could completely ignore the tooling and just take the resulting static Website and deploy it (or not).

If we really want to discuss tooling, then there should be a proper feature matrix with pros and cons and the best tool may be selected. (I actually have done that quite extensively and even have double checked the assessment against other similar projects, like Apache Shiro.)

I have presented some ideas and sofar nobody said anything about the content. Nobody has contributed to the documentation or modified the appearance. Dogmatic discussions are not my thing, I'd rather like to focus on the actual outcome.

[gitmotte]

To be honest I have no idea how maven sites are prettified. I only use https://maven.apache.org/skins/maven-fluido-skin/. But this is only for company internal stuff. I use AsciiDoctor to create the sites. But to set it up was hard to get all needed plugins running.

I've never used a skin for the maven site plugin, but [Reflow 2 Maven Skin] (https://devacfr.github.io/reflow-maven-skin/), found at https://maven.apache.org/skins/, looks good. I don't know why there should be a need for a nice looking website - better invest the time in good documentation.

Why I suggest a tool? Because the discussion here has already brought some tools into play (i.e. Hugo, Ascii Doctor, Sphinx, Antora) but all seem to need a learning curve and have dependencies on other runtime environments (python) to run.

So why not just use the most obvious tool for a java library.

[wumpz]

Looks good. I will give it a try at least for my internal pages to get kind of a feeling how it works.

[manticore-projects]

Closed, since there is a website now: https://jsqlparser.github.io/JSqlParser