From 735d7dbfeb2f1de870f3caafd045661d2f7b986a Mon Sep 17 00:00:00 2001 From: Svjatoslav Agejenko Date: Sun, 27 Sep 2026 18:04:10 +0300 Subject: [PATCH] build: upgrade to Java 21 and reorganize documentation Bump java.version, maven.compiler source/target and the compiler plugin configuration from 1.8 to 21. Rename doc/ to Documentation/ following the house convention, updating .gitignore, Tools/Update web site and AGENTS.md accordingly. Reorganize the Documentation pages into prerequisite reading order: the overview page leads with Introduction and Usage before Installation and Source code; the CLI page explains class selection concepts before the argument reference; the Java API page covers Maven embedding before the examples. Fix stale content: retarget sixth-3d links to the renamed Aukio 3D project site, update CLI examples to aukio-3d artifacts and packages, and mark the embedded-project example as outdated. Align with the shared doc-set conventions: add the canonical style.css, link it from every page via HTML_HEAD, give every heading a CUSTOM_ID, use anchor-form back-links on sub-pages, and record the conventions in AGENTS.md. --- .gitignore | 4 +- AGENTS.md | 29 +++++-- .../JavaInspect full project.png | Bin {doc => Documentation}/JavaInspect.dot | 0 {doc => Documentation}/JavaInspect.png | Bin .../Usage from CLI/index.org | 74 +++++++++--------- .../Usage via Java API/index.org | 74 ++++++++++-------- {doc => Documentation}/example-thumbnail.png | Bin {doc => Documentation}/example.png | Bin {doc => Documentation}/index.org | 22 +++--- {doc => Documentation}/legend.png | Bin Documentation/style.css | 35 +++++++++ Tools/Update web site | 18 ++--- pom.xml | 12 +-- 14 files changed, 166 insertions(+), 102 deletions(-) rename {doc => Documentation}/JavaInspect full project.png (100%) rename {doc => Documentation}/JavaInspect.dot (100%) rename {doc => Documentation}/JavaInspect.png (100%) rename {doc => Documentation}/Usage from CLI/index.org (89%) rename {doc => Documentation}/Usage via Java API/index.org (92%) rename {doc => Documentation}/example-thumbnail.png (100%) rename {doc => Documentation}/example.png (100%) rename {doc => Documentation}/index.org (94%) rename {doc => Documentation}/legend.png (100%) create mode 100644 Documentation/style.css diff --git a/.gitignore b/.gitignore index 6c235d2..f532c33 100755 --- a/.gitignore +++ b/.gitignore @@ -9,5 +9,5 @@ dependency-reduced-pom.xml /JavaInspect.dot /JavaInspect.svg *.html -/doc/graphs/ -/doc/apidocs/ +/Documentation/graphs/ +/Documentation/apidocs/ diff --git a/AGENTS.md b/AGENTS.md index 93ead91..ee1a7ba 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -228,8 +228,27 @@ mvn exec:java -Dexec.mainClass="eu.svjatoslav.inspector.java.RenderJavaInspect" # Documentation -| Path | Topic | -|-----------------|-------------------------------------------------------| -| `doc/index.org` | Main documentation, usage examples, Maven integration | -| `doc/apidocs/` | Generated Javadoc | -| `COPYING` | CC0 license full text | \ No newline at end of file +| Path | Topic | +|-----------------------------------|-------------------------------------------------------| +| `Documentation/index.org` | Main documentation, usage examples, Maven integration | +| `Documentation/apidocs/` | Generated Javadoc | +| `COPYING` | CC0 license full text | + +## Documentation conventions + +- Every heading carries a `:PROPERTIES:` drawer with `:CUSTOM_ID: + ` immediately after the heading line — without it + org-html export emits `org` anchors. Sub-pages also carry a + file-level drawer (before `#+SETUPFILE:`) as identity marker. +- Every page links the shared stylesheet via `#+HTML_HEAD: + ` (`../style.css` in + subdirectories); `Documentation/style.css` is copied verbatim from + sibling projects. +- Sub-page back-links use the anchor form + `[[file:../index.html#outline-container-
][<- Back to index]]`. +- Verify with `emacs --batch -l ~/.emacs --visit=.org + --funcall=org-html-export-to-html --kill` — no "Unable to resolve + link" output and no `outline-container-org` ids in the HTML. + The darksun theme renders top-level sections as tabs; screenshot + each tab via its `#` anchor URL with headless Chrome + (`--virtual-time-budget=8000`). \ No newline at end of file diff --git a/doc/JavaInspect full project.png b/Documentation/JavaInspect full project.png similarity index 100% rename from doc/JavaInspect full project.png rename to Documentation/JavaInspect full project.png diff --git a/doc/JavaInspect.dot b/Documentation/JavaInspect.dot similarity index 100% rename from doc/JavaInspect.dot rename to Documentation/JavaInspect.dot diff --git a/doc/JavaInspect.png b/Documentation/JavaInspect.png similarity index 100% rename from doc/JavaInspect.png rename to Documentation/JavaInspect.png diff --git a/doc/Usage from CLI/index.org b/Documentation/Usage from CLI/index.org similarity index 89% rename from doc/Usage from CLI/index.org rename to Documentation/Usage from CLI/index.org index 7311d6a..32764bc 100644 --- a/doc/Usage from CLI/index.org +++ b/Documentation/Usage from CLI/index.org @@ -11,38 +11,9 @@ #+OPTIONS: H:20 num:20 #+OPTIONS: author:nil -[[file:../index.org][Back to main documentation]] +#+HTML_HEAD: -* Commandline arguments -:PROPERTIES: -:CUSTOM_ID: available-commandline-arguments -:END: - - -- -j (existing files)... :: JAR file(s) to render. - -- -c (existing directories)... :: Classpath directories - -- -n (string) :: Graph name. (default: "graph") - -- --debug :: Show debug info. - -- -h, --help :: Show commandline usage help. - -- -k :: Keep dot file. - -- -ho :: - Hide orphaned classes. - -- -w (one to many strings)... :: Whitelist glob(s). - -- -b (one to many strings)... :: Blacklist glob(s). - -- -r (one to many strings)... :: root class(es). - -- -d (existing directory) :: Target directory. Default is current directory. - -- -t (options: png, svg) :: Target image type. Default is: svg. +[[file:../index.html#outline-container-usage][<- Back to index]] * Specifying classes to render :PROPERTIES: @@ -77,6 +48,37 @@ JavaInspect uses the following algorithm to add classes to the graph: recursively discovers all classes referenced by root classes and adds them to the graph. +* Commandline arguments +:PROPERTIES: +:CUSTOM_ID: available-commandline-arguments +:END: + + +- -j (existing files)... :: JAR file(s) to render. + +- -c (existing directories)... :: Classpath directories + +- -n (string) :: Graph name. (default: "graph") + +- --debug :: Show debug info. + +- -h, --help :: Show commandline usage help. + +- -k :: Keep dot file. + +- -ho :: + Hide orphaned classes. + +- -w (one to many strings)... :: Whitelist glob(s). + +- -b (one to many strings)... :: Blacklist glob(s). + +- -r (one to many strings)... :: root class(es). + +- -d (existing directory) :: Target directory. Default is current directory. + +- -t (options: png, svg) :: Target image type. Default is: svg. + * Examples :PROPERTIES: :CUSTOM_ID: examples @@ -86,8 +88,8 @@ Visualize a Java JAR file with all classes, hiding orphaned classes: #+begin_src sh javainspect \ - -j target/sixth-3d-*-SNAPSHOT.jar \ - -d doc/graphs/ \ + -j target/aukio-3d-*-SNAPSHOT.jar \ + -d Documentation/graphs/ \ -n "All classes" \ -t png -ho #+end_src @@ -96,10 +98,10 @@ Visualize a Java JAR file with a whitelist filter, hiding orphaned classes: #+begin_src sh javainspect \ - -j target/sixth-3d-*-SNAPSHOT.jar \ - -d doc/graphs/ \ + -j target/aukio-3d-*-SNAPSHOT.jar \ + -d Documentation/graphs/ \ -n "GUI" \ -t png \ - -w "eu.svjatoslav.sixth.e3d.gui.*" \ + -w "eu.svjatoslav.aukio.e3d.gui.*" \ -ho #+end_src diff --git a/doc/Usage via Java API/index.org b/Documentation/Usage via Java API/index.org similarity index 92% rename from doc/Usage via Java API/index.org rename to Documentation/Usage via Java API/index.org index a44747b..7e19641 100644 --- a/doc/Usage via Java API/index.org +++ b/Documentation/Usage via Java API/index.org @@ -11,7 +11,9 @@ #+OPTIONS: H:20 num:20 #+OPTIONS: author:nil -[[file:../index.org][Back to main documentation]] +#+HTML_HEAD: + +[[file:../index.html#outline-container-usage][<- Back to index]] * Overview :PROPERTIES: @@ -48,7 +50,42 @@ The control code generally does the following: + Keep intermediate GraphViz DOT file for later inspection. 5. Render the graph. +* Embedding JavaInspect in your Maven project +:PROPERTIES: +:CUSTOM_ID: embedding-javainspect-in-your-maven-project +:END: + +Declare JavaInspect as dependency: +#+BEGIN_SRC xml + + ... + + eu.svjatoslav + javainspect + 1.8 + + ... + +#+END_SRC + + +Add Maven repository to retrieve artifact from: +#+BEGIN_SRC xml + + ... + + svjatoslav.eu + Svjatoslav repository + https://www3.svjatoslav.eu/maven/ + + ... + +#+END_SRC + * Examples +:PROPERTIES: +:CUSTOM_ID: examples +:END: ** Example 1: Hand-picked objects :PROPERTIES: :CUSTOM_ID: example-1-individually-picked-objects @@ -90,37 +127,8 @@ Result: :CUSTOM_ID: example-2-graphviz-embedded-in-another-project :END: +*Outdated:* this example refers to the old Sixth project (since renamed +Aukio); =DataGraph.java= no longer exists there. Kept for reference. + 1. Download a [[https://www2.svjatoslav.eu/gitweb/?p=sixth.git;a=snapshot;h=HEAD;sf=tgz][Sixth project snapshot]]. 2. Inspect and run *DataGraph.java*. - -* Embedding JavaInspect in your Maven project -:PROPERTIES: -:CUSTOM_ID: embedding-javainspect-in-your-maven-project -:END: - -Declare JavaInspect as dependency: -#+BEGIN_SRC xml - - ... - - eu.svjatoslav - javainspect - 1.8 - - ... - -#+END_SRC - - -Add Maven repository to retrieve artifact from: -#+BEGIN_SRC xml - - ... - - svjatoslav.eu - Svjatoslav repository - https://www3.svjatoslav.eu/maven/ - - ... - -#+END_SRC diff --git a/doc/example-thumbnail.png b/Documentation/example-thumbnail.png similarity index 100% rename from doc/example-thumbnail.png rename to Documentation/example-thumbnail.png diff --git a/doc/example.png b/Documentation/example.png similarity index 100% rename from doc/example.png rename to Documentation/example.png diff --git a/doc/index.org b/Documentation/index.org similarity index 94% rename from doc/index.org rename to Documentation/index.org index 020b2b9..6372754 100644 --- a/doc/index.org +++ b/Documentation/index.org @@ -8,6 +8,8 @@ #+OPTIONS: H:20 num:20 #+OPTIONS: author:nil +#+HTML_HEAD: + * Introduction :PROPERTIES: :CUSTOM_ID: overview @@ -16,7 +18,7 @@ *JavaInspect* simplifies understanding source code by automatically visualizing program structure. See example graphs: -- [[https://www3.svjatoslav.eu/projects/sixth-3d/graphs/][Diagrams]] for [[https://www3.svjatoslav.eu/projects/sixth-3d/][Sixth 3D engine project]]. +- [[https://www3.svjatoslav.eu/projects/aukio-3d/graphs/][Diagrams]] for [[https://www3.svjatoslav.eu/projects/aukio-3d/][Aukio 3D engine project]]. + [[file:graphs/][Diagrams for JavaInspect project itself]]. *A very simple example:* @@ -29,8 +31,6 @@ JavaInspect can be used as a [[file:Usage from CLI/][standalone commandline util [[file:Usage via Java API/][Java library]]. It uses Java's built-in reflection to discover and visualize any part of a Java program. -See [[#usage][usage]] to learn how to use JavaInspect. - After discovering application structure and optionally filtering out unimportant parts, JavaInspect produces a GraphViz DOT file describing the data to visualize. It then launches [[https://graphviz.org/][GraphViz]] to generate the @@ -45,6 +45,14 @@ Similar or alternative solutions: + http://www.class-visualizer.net/ + [[https://github.com/pahen/madge][Madge - similar tool for JavaScript]] +* Usage +:PROPERTIES: +:CUSTOM_ID: usage +:END: +JavaInspect can be used in two ways: ++ [[file:Usage from CLI/][As a standalone commandline utility]] ++ [[file:Usage via Java API/][As a Java library embedded in your project]] + * Installation :PROPERTIES: :CUSTOM_ID: installation @@ -76,14 +84,6 @@ After installation, new commandline tool should be available Quick commandline usage help can be viewed by issuing : javainspect --help -* Usage -:PROPERTIES: -:CUSTOM_ID: usage -:END: -JavaInspect can be used in two ways: -+ [[file:Usage from CLI/][As a standalone commandline utility]] -+ [[file:Usage via Java API/][As a Java library embedded in your project]] - * Source code :PROPERTIES: :CUSTOM_ID: getting-the-source-code diff --git a/doc/legend.png b/Documentation/legend.png similarity index 100% rename from doc/legend.png rename to Documentation/legend.png diff --git a/Documentation/style.css b/Documentation/style.css new file mode 100644 index 0000000..3403e0e --- /dev/null +++ b/Documentation/style.css @@ -0,0 +1,35 @@ +.flex-center { + display: flex; + justify-content: center; +} + +.flex-center video { + width: min(90%, 1000px); + height: auto; +} + +.responsive-img { + width: min(100%, 1000px); + height: auto; +} + +/* === SVG diagram theme === */ +svg > rect:first-child { + fill: #061018; +} + +svg text[fill="#666"], +svg text[fill="#999"] { + fill: #aaa !important; +} + +svg line[stroke="#ccc"] { + stroke: #445566 !important; +} + +svg { + background-color: #061018; + border-radius: 8px; + display: block; + margin: 0 auto; +} \ No newline at end of file diff --git a/Tools/Update web site b/Tools/Update web site index a58ff9c..c92c839 100755 --- a/Tools/Update web site +++ b/Tools/Update web site @@ -26,10 +26,10 @@ export_org_to_html() { } export_org_files_to_html() { - echo "🔍 Searching for .org files in doc/ ..." + echo "🔍 Searching for .org files in Documentation/ ..." echo "=======================================" - mapfile -t ORG_FILES < <(find doc -type f -name "*.org" | sort) + mapfile -t ORG_FILES < <(find Documentation -type f -name "*.org" | sort) if [ ${#ORG_FILES[@]} -eq 0 ]; then echo "❌ No .org files found!" @@ -61,21 +61,21 @@ export_org_files_to_html() { } build_visualization_graphs() { - rm -rf doc/graphs/ - mkdir -p doc/graphs/ + rm -rf Documentation/graphs/ + mkdir -p Documentation/graphs/ # Generate self-visualization of JavaInspect - javainspect -j target/javainspect.jar -d doc/graphs/ -n "All classes" -t png -w "eu.svjatoslav.inspector.java.*" -ho + javainspect -j target/javainspect.jar -d Documentation/graphs/ -n "All classes" -t png -w "eu.svjatoslav.inspector.java.*" -ho - meviz index -w doc/graphs/ -t "JavaInspect classes" + meviz index -w Documentation/graphs/ -t "JavaInspect classes" } # Build project jar file and JavaDocs mvn clean package # Put generated JavaDoc HTML files to documentation directory -rm -rf doc/apidocs/ -cp -r target/apidocs/ doc/ +rm -rf Documentation/apidocs/ +cp -r target/apidocs/ Documentation/ # Publish Emacs org-mode files into HTML format export_org_files_to_html @@ -86,7 +86,7 @@ build_visualization_graphs ## Upload assembled documentation to server echo "📤 Uploading to server..." -rsync -avz --delete -e 'ssh -p 10006' doc/ \ +rsync -avz --delete -e 'ssh -p 10006' Documentation/ \ n0@www3.svjatoslav.eu:/mnt/big/projects/javainspect/ if [ $? -eq 0 ]; then diff --git a/pom.xml b/pom.xml index e27daad..f253391 100644 --- a/pom.xml +++ b/pom.xml @@ -8,9 +8,9 @@ Utility to visualize Java code - 1.8 - 1.8 - 1.8 + 21 + 21 + 21 UTF-8 UTF-8 @@ -28,8 +28,8 @@ maven-compiler-plugin 3.8.1 - 1.8 - 1.8 + 21 + 21 true UTF-8 @@ -120,7 +120,7 @@ eu.svjatoslav svjatoslavcommons - 1.9 + 2.0.0 eu.svjatoslav -- 2.20.1