Sphinx Website

[manticore-projects]

Summary

Add a HTML5 Website based on Sphinx:

a) scales on devices (from mobile phone to very large screens)
b) theme-able (shown is a modified theme based on Read The Docs, being cleaner and scaling on large screens much better, landing page added)
c) CSS customizable (you can change the Accent Colours)
d) integrated search function
e) please adjust/change the icons according to your needs

Integrate the Sphinx Website into the Gradle Build:

d) derive the actual Version Number (Release and Snapshot) from the GIT Tags
e) generate a clean Changelog from GIT (template can be customized)
f) update all Version references (Maven Artifact, Downloads etc) automatically

Add some content:
g) explain the Contribution process
h) link to JSQLFormatter online for Statement Testing and Visualisation
i) add the Railroad Diagrams explaining the syntax (but without Reserved Keywords yet)

Added Object Tree Visualization tools, which will generate a TreeNode based tree structure explaining the parsed java Object Tree.

select 1 from dual where a=b;

SQL Text
  └─Statements: net.sf.jsqlparser.statement.select.Select
     └─selectBody: net.sf.jsqlparser.statement.select.PlainSelect
        ├─selectItems -> Collection<SelectExpressionItem>
        │  └─selectItems: net.sf.jsqlparser.statement.select.SelectExpressionItem
        │     └─LongValue: 1
        ├─Table: dual
        └─where: net.sf.jsqlparser.expression.operators.relational.EqualsTo
           ├─Column: a
           └─Column: b

Build Instructions

1. you will need Python Sphinx and GIT installed
2. build the website via gradle sphinx
3. optionally, place the Sphinx HTML theme into the _themes folder and/or provide a custom.css file

Preview

Live preview: http://manticore-projects.com/JSQLParser/index.html

Static preview image:

Static preview package:
sphinx.zip

Attention

It has been built upon the Keywords PR, mainly because of the build infrastructure and the keywords documentation.
So the Keywords PR is included and need to be accepted first (or dropped altogether in favor of this Sphinx PR).

[manticore-projects]

I have added a Github Action, that builds the Website on Commit to Master and deploys the static Site to GH Pages.

Demo: https://manticore-projects.github.io/JSqlParser/

[wumpz]

Cool. And using this the sphinx sources somewhere within the master branch are generated and published to Github pages?

[manticore-projects]

yes.

[wumpz]

Why all these implements Serializable stuff?

[manticore-projects]

On Thu, 2022-12-22 at 14:46 -0800, Tobias wrote: Why all these implements Serializable stuff?

The tree viewer, i need to serialize the objects first into xml before applying xpath and deserialize.

[manticore-projects]

Please also disable CSS in Codacy. Thanks.

Kind reminder, since I am not allowed to do that by myself unfortunately.

[wumpz]

Disabled CSSLint, StyleLint in Codacy.

[manticore-projects]

Disabled CSSLint, StyleLint in Codacy.

Thanks. Will you accept the PR or do you expect me to push/update and rerun the Codacy CI-Tests before?

[wumpz]

The tree viewer, i need to serialize the objects first into xml before
applying xpath and deserialize.

Where is this xpath parser implemented? I did not find it at first glance. You know this serialization stuff is somehow deprecated: https://www.securityinfowatch.com/cybersecurity/information-security/article/12420169/oracle-plans-to-end-java-serialization-but-thats-not-the-end-of-the-story. I would like to find another way.

To make things easier I could make node generation for every production a default. Since performance is not that important anymore. I measured a decrease of 20% for queries.

[manticore-projects]

Where is this xpath parser implemented?

Separately, in JSQLFormatter only.

I did not find it at first glance. You know this serialization stuff is somehow deprecated: https://www.securityinfowatch.com/cybersecurity/information-security/article/12420169/oracle-plans-to-end-java-serialization-but-thats-not-the-end-of-the-story. I would like to find another way.

There are other ways like Jackson, however that would introduce Third Party dependencies because they all rely on a kind of annotation and implementation of Serializers and De-Serializers.

In your own link its written, that "Oracle plans ..." since 2018 and nothing has happened since. Even if anything happens, it would depend on Java 19 plus while we still (want to) maintain Java 8 compliance for a good reason.

Companies still run JRE/JDK 8 and won't upgrade.

Last but not least, I think some Serializable Objects were there already, I just added a few more but did not introduce anything unheard of before.

[wumpz]

Fair point.

[wumpz]

Could you check this Codacy checks again (making a commit). Codacy somehow does not to allow me to reevaluate specific commits again.

[manticore-projects]

Pew, finally!

[manticore-projects]

Integrate the RR diagram into the website.
Applied a neutral Sphinx theme.

Preview: https://manticore-projects.github.io/JSqlParser/syntax.html

Besser als das wird es nicht!
Btw, die Aenderung der Versions Nummer in der Readme koennten wir uns sparen mit der WebSite, welche die Versionierung automatisch verfolgt.

[wumpz]

So this is ready to be merged?

[manticore-projects]

So this is ready to be merged?

yes, Sir.