From: Svjatoslav Agejenko Date: Sat, 18 Apr 2026 13:45:34 +0000 (+0300) Subject: docs: reorganize documentation into modular structure X-Git-Url: http://www2.svjatoslav.eu/gitweb/?a=commitdiff_plain;h=refs%2Fheads%2Ffeat;p=javainspect.git docs: reorganize documentation into modular structure Split monolithic index.org into separate pages for CLI and Java API usage with proper subdirectory organization. Convert org-mode links from ID-based to CUSTOM_ID and file references for reliable HTML export. Simplify build script output and fix language clarity issues throughout. Update Maven dependency version to 1.8. --- diff --git a/Tools/Update web site b/Tools/Update web site index 86d62a0..a58ff9c 100755 --- a/Tools/Update web site +++ b/Tools/Update web site @@ -1,5 +1,5 @@ #!/bin/bash -cd "${0%/*}"; if [ "$1" != "T" ]; then gnome-terminal -- "$0" T; exit; fi; +cd "${0%/*}"; if [ "$1" != "T" ]; then gnome-terminal -e "'$0' T"; exit; fi; cd .. @@ -61,58 +61,31 @@ export_org_files_to_html() { } build_visualization_graphs() { - echo "🎨 Generating class visualization graphs..." - echo "=======================================" - rm -rf doc/graphs/ mkdir -p doc/graphs/ - # JavaInspect analyzing itself - meta visualization! - javainspect -j target/javainspect.jar -d doc/graphs/ -n "All classes" -t png - javainspect -j target/javainspect.jar -d doc/graphs/ -n "Inspector" -t png -w "eu.svjatoslav.inspector.*" - javainspect -j target/javainspect.jar -d doc/graphs/ -n "Java parser" -t png -w "eu.svjatoslav.inspector.java.*" + # Generate self-visualization of JavaInspect + javainspect -j target/javainspect.jar -d doc/graphs/ -n "All classes" -t png -w "eu.svjatoslav.inspector.java.*" -ho - # Generate index page for graphs meviz index -w doc/graphs/ -t "JavaInspect classes" - - echo "✓ Visualization graphs generated" - echo "" } # Build project jar file and JavaDocs -echo "🔨 Building project..." -echo "=======================================" mvn clean package -if [ $? -ne 0 ]; then - echo "✗ Maven build failed!" - echo "" - echo "Press ENTER to close this window." - read - exit 1 -fi - -echo "✓ Maven build completed" -echo "" - # Put generated JavaDoc HTML files to documentation directory -echo "📚 Copying JavaDocs..." -echo "=======================================" rm -rf doc/apidocs/ cp -r target/apidocs/ doc/ -echo "✓ JavaDocs copied to doc/apidocs/" -echo "" - # Publish Emacs org-mode files into HTML format export_org_files_to_html # Generate nice looking code visualization diagrams build_visualization_graphs + ## Upload assembled documentation to server echo "📤 Uploading to server..." -echo "=======================================" rsync -avz --delete -e 'ssh -p 10006' doc/ \ n0@www3.svjatoslav.eu:/mnt/big/projects/javainspect/ @@ -124,4 +97,4 @@ fi echo "" echo "Press ENTER to close this window." -read \ No newline at end of file +read diff --git a/doc/Usage from CLI/index.org b/doc/Usage from CLI/index.org new file mode 100644 index 0000000..7311d6a --- /dev/null +++ b/doc/Usage from CLI/index.org @@ -0,0 +1,105 @@ +:PROPERTIES: +:CUSTOM_ID: usage-from-cli +:END: +#+SETUPFILE: ~/.emacs.d/org-styles/html/darksun.theme +#+TITLE: JavaInspect - usage from commandline +#+LANGUAGE: en +#+LATEX_HEADER: \usepackage[margin=1.0in]{geometry} +#+LATEX_HEADER: \usepackage{parskip} +#+LATEX_HEADER: \usepackage[none]{hyphenat} + +#+OPTIONS: H:20 num:20 +#+OPTIONS: author:nil + +[[file:../index.org][Back to main documentation]] + +* 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. + +* Specifying classes to render +:PROPERTIES: +:CUSTOM_ID: specifying-classes-to-render +:END: + +A typical Java application has immense complexity. Beyond code written +by the project's developers, there are typically many frameworks, +libraries, and the Java standard library. + +Since JavaInspect uses reflection, it cannot easily distinguish between +these sources. Usually you want to visualize only the code developed +for your project, excluding frameworks like Spring. If you visualize +all classes reachable from your project, the graph becomes huge and +incomprehensible. + +JavaInspect can analyze compiled Java classes in two modes: +1. Provide JAR files using the *-j* option. +2. Provide filesystem directories as classpath roots using the *-c* option. + +JavaInspect uses the following algorithm to add classes to the graph: + +- All classes found in JAR files are added to the graph by default. +- Classes found in filesystem directories are not added by default + unless explicitly referenced. (TODO: for consistency, these should + also be added by default) +- If a whitelist is specified (*-w* option), classes not matching the + whitelist patterns are removed from the graph. +- If a blacklist is specified (*-b* option), classes matching the + blacklist patterns are removed from the graph. +- Root classes can be specified using the *-r* option. JavaInspect + recursively discovers all classes referenced by root classes and + adds them to the graph. + +* Examples +:PROPERTIES: +:CUSTOM_ID: examples +:END: + +Visualize a Java JAR file with all classes, hiding orphaned classes: + +#+begin_src sh + javainspect \ + -j target/sixth-3d-*-SNAPSHOT.jar \ + -d doc/graphs/ \ + -n "All classes" \ + -t png -ho +#+end_src + +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/ \ + -n "GUI" \ + -t png \ + -w "eu.svjatoslav.sixth.e3d.gui.*" \ + -ho +#+end_src diff --git a/doc/Usage via Java API/index.org b/doc/Usage via Java API/index.org new file mode 100644 index 0000000..a44747b --- /dev/null +++ b/doc/Usage via Java API/index.org @@ -0,0 +1,126 @@ +:PROPERTIES: +:CUSTOM_ID: usage-via-java-api +:END: +#+SETUPFILE: ~/.emacs.d/org-styles/html/darksun.theme +#+TITLE: JavaInspect - Usage via Java API +#+LANGUAGE: en +#+LATEX_HEADER: \usepackage[margin=1.0in]{geometry} +#+LATEX_HEADER: \usepackage{parskip} +#+LATEX_HEADER: \usepackage[none]{hyphenat} + +#+OPTIONS: H:20 num:20 +#+OPTIONS: author:nil + +[[file:../index.org][Back to main documentation]] + +* Overview +:PROPERTIES: +:CUSTOM_ID: overview +:END: +Classes to be visualized must be available in the classpath. + +To include JavaInspect in the same classpath as your projects, there are +two approaches: + +1. Add JavaInspect as a dependency in your project. + +2. Create a new Java project specifically for visualizing other + projects, and include both JavaInspect and your project's binary + artifacts (JARs) in the classpath. Binary JARs (without source code) + are sufficient since JavaInspect operates via reflection. + +Write simple control/configuration code for each project. I typically +place this code in JUnit test directories since it doesn't need to be +compiled into the final product or artifact. + +The control code generally does the following: +1. Create a graph object. +2. Java reflection/classloaders do not provide a mechanism to discover + all classes under a package. Therefore, manually add at least some + classes to the graph. For each class added, JavaInspect recursively + inspects it and adds all referenced classes. +3. Graphs can easily become very large and complex, so optionally filter + important code using classname [[https://en.wikipedia.org/wiki/Glob_(programming)][glob]] pattern blacklists and/or + whitelists. +4. Optionally tune rendering parameters: + + Remove orphaned classes (classes with no references) from the graph. + + Specify target directory for generated files (default: current directory). + + Keep intermediate GraphViz DOT file for later inspection. +5. Render the graph. + +* Examples +** Example 1: Hand-picked objects +:PROPERTIES: +:CUSTOM_ID: example-1-individually-picked-objects +:END: +This example generates a class graph from hand-picked classes, visualizing +JavaInspect itself. + +#+BEGIN_SRC java + +// Create graph +final ClassGraph graph = new ClassGraph(); + +// Add an object to the graph. JavaInspect detects the class from the object. +graph.add(graph); + +// Also add a class directly. +graph.add(Utils.class); + +// Keep the intermediate GraphViz DOT file for reference. +graph.setKeepDotFile(true); + +// Generate an image named "JavaInspect.png" in the current directory +graph.generateGraph("JavaInspect"); + +#+END_SRC + +Compact version: +#+BEGIN_SRC java +new ClassGraph().add(randomObject, RandomClass.class) + .setKeepDotFile(true).generateGraph("JavaInspect"); +#+END_SRC + +Result: +- Generated DOT file: [[file:../JavaInspect.dot][JavaInspect.dot]] +- Generated PNG image: [[file:../JavaInspect.png][JavaInspect.png]] + +** Example 2: Embedded in another project +:PROPERTIES: +:CUSTOM_ID: example-2-graphviz-embedded-in-another-project +:END: + +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/index.org b/doc/index.org index 145282f..020b2b9 100644 --- a/doc/index.org +++ b/doc/index.org @@ -13,37 +13,28 @@ :CUSTOM_ID: overview :END: -*JavaInspect* utility simplifies understanding the computer program -code by automatically visualizing its structure. - -[[https://www3.svjatoslav.eu/projects/sixth-3d/graphs/][See example produced graphs]] for [[https://www3.svjatoslav.eu/projects/sixth-3d/][Sixth 3D - 3D engine project]]. - -JavaInspect can be used as a [[id:acf1896a-74b4-4914-acf6-a77075e07f25][standalone commandline utility]] as well as -[[id:bbeeffc8-3767-440d-8d93-ec9124dd60ee][java library]]. JavaInspect uses primarily Java built-in reflection to -discover and visualize any part of Java program. - -JavaInspect currently has no graphical user interface, configuration -files, embedded scripting support, direct Maven, Gradle or Ant -integration. See [[id:2ad2889e-6c95-4662-b3f4-2c341fc74522][usage]] to learn how to instuct Javainspect what to do. - -After discovering application structure and optionally filtering out -unimportant parts, JavaInspect produces GraphViz dot file that -describes data to be visualized. Then launches [[https://graphviz.org/][GraphViz]] to generate -bitmap graph in PNG or SVG format. - -Notes: -+ JavaInspect is developed and tested so far only on GNU/Linux. +*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]]. ++ [[file:graphs/][Diagrams for JavaInspect project itself]]. *A very simple example:* - [[file:example.png][file:example-thumbnail.png]] Graph legend: file:legend.png +JavaInspect can be used as a [[file:Usage from CLI/][standalone commandline utility]] or as a +[[file:Usage via Java API/][Java library]]. It uses Java's built-in reflection to discover and +visualize any part of a Java program. -+ [[https://www3.svjatoslav.eu/projects/sixth-3d/graphs/][See example produced graphs]] for [[https://www3.svjatoslav.eu/projects/sixth-3d/][Sixth 3D - 3D engine project]]. +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 +graph image in PNG or SVG format. ** See also :PROPERTIES: @@ -58,20 +49,20 @@ Similar or alternative solutions: :PROPERTIES: :CUSTOM_ID: installation :END: -[[http://www.graphviz.org/][GraphViz]] - shall be installed on the computer. +[[http://www.graphviz.org/][GraphViz]] must be installed on your system. -On Ubuntu/Debian GraphViz can be installed using: +On Ubuntu/Debian, install GraphViz using: #+BEGIN_SRC sh sudo apt-get install graphviz #+END_SRC To use JavaInspect via Java API, no further installation is needed. JavaInspect will be embedded into your project as dependency. -This is described in [[id:bbeeffc8-3767-440d-8d93-ec9124dd60ee][usage via Java API]]. It will expect GraphViz to be +This is described in [[file:Usage via Java API/][usage via Java API]]. It will expect GraphViz to be available in the system. To use JavaInspect as a commandline tool, JavaInspect source -repository has to be cloned locally. See: [[id:c47ff9a6-d737-4b73-9393-1c63d2ca1101][Getting the source code]]. +repository has to be cloned locally. See: [[#getting-the-source-code][Getting the source code]]. Then study and execute installation script: #+begin_src sh @@ -87,137 +78,14 @@ Quick commandline usage help can be viewed by issuing * Usage :PROPERTIES: -:ID: 2ad2889e-6c95-4662-b3f4-2c341fc74522 :CUSTOM_ID: usage :END: -JavaInspect utility can be used in 2 different ways: -+ [[id:acf1896a-74b4-4914-acf6-a77075e07f25][As standalone commandline utility]] -+ [[id:bbeeffc8-3767-440d-8d93-ec9124dd60ee][As embedded Java library via Java API]] - -** Usage via Java API -:PROPERTIES: -:ID: bbeeffc8-3767-440d-8d93-ec9124dd60ee -:CUSTOM_ID: usage-via-java-api -:END: -Requires that classes to be visualised are available in the classpath. - -To get JavaInspect into same classpath with your projecs I so far came -up with 2 solutions: - -1. Add JavaInspect library in your project as a dependency. - -2. Create new Java project for the purpose visualizing your other - projects and include JavaInspect and your projecs binary artifacts - (Jar's) into new project classpath. Built binary Jar's (with no - source code) are sufficient because JavaInspect operates via - reflection. - -Simple Java based control/configuration code needs to be written for -each project. I usually put such code into directories devoted for -JUnit tests. Because it needs not to be compiled/embedded into final -product or project artifact I'm just willing to visualize. - -Control code in general does the following: -1. Create graph object. -2. Java reflection/classloaders does not provide mechanism for - discovering all classes under given package. Therefore you need to - declare at least some classes to be added to the graph by manually - adding individual classes to the graph. For every class added to - the graph, GraphViz will recursively inspect it and add all - referecned classes to the graph as well. -3. Graphs easilly get very big and complex so optionally we filter - important code using classname [[https://en.wikipedia.org/wiki/Glob_(programming)][glob]] patterns based blacklist and/or - whitelist. -4. Optionally we can tune some rendering parameters like: - + Possibility to remove orphaned classes (classes with no - references) from the graph. - + Specify target directory for generated visualization - files. (Default is current directory) - + Keep intermediate GraphViz dot file for later inspection. -5. Render graph. - - -*** Example 1: individually picked objects -:PROPERTIES: -:CUSTOM_ID: example-1-individually-picked-objects -:END: -This example demonstrates generating of class graph from hand picked -classes and visualizing GraphViz itself. - -#+BEGIN_SRC java - -// Create graph -final ClassGraph graph = new ClassGraph(); - -// Add some random object to the graph. GraphViz will detect Class from -// the object. -graph.add(graph); - -// Also add some random class to the graph. -graph.add(Utils.class); - -// Keep intermediary GraphViz DOT file for reference. -graph.setKeepDotFile(true); - -// Produce bitmap image titled "JavaInspect.png" to the user Desktop -// directory -graph.generateGraph("JavaInspect"); - -#+END_SRC - -Note: if desired, more compact version of the above: -#+BEGIN_SRC java -new ClassGraph().add(randomObject, RandomClass.class) - .setKeepDotFile(true).generateGraph("JavaInspect"); -#+END_SRC - - -Result: - - Generated DOT file: [[file:JavaInspect.dot][JavaInspect.dot]] - - Generated PNG image: [[file:JavaInspect.png][JavaInspect.png]] - -*** Example 2: GraphViz embedded in another project -:PROPERTIES: -:CUSTOM_ID: example-2-graphviz-embedded-in-another-project -:END: -1. Download project Sixth [[https://www2.svjatoslav.eu/gitweb/?p=sixth.git;a=snapshot;h=HEAD;sf=tgz][code 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.7 - - ... - -#+END_SRC - - -Add Maven repository to retrieve artifact from: -#+BEGIN_SRC xml - - ... - - svjatoslav.eu - Svjatoslav repository - https://www3.svjatoslav.eu/maven/ - - ... - -#+END_SRC +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: -:ID: c47ff9a6-d737-4b73-9393-1c63d2ca1101 :CUSTOM_ID: getting-the-source-code :END: diff --git a/doc/upsage from cli/index.org b/doc/upsage from cli/index.org deleted file mode 100644 index 91ec55e..0000000 --- a/doc/upsage from cli/index.org +++ /dev/null @@ -1,112 +0,0 @@ -:PROPERTIES: -:ID: acf1896a-74b4-4914-acf6-a77075e07f25 -:END: -#+SETUPFILE: ~/.emacs.d/org-styles/html/darksun.theme -#+TITLE: JavaInspect - usage from commandline -#+LANGUAGE: en -#+LATEX_HEADER: \usepackage[margin=1.0in]{geometry} -#+LATEX_HEADER: \usepackage{parskip} -#+LATEX_HEADER: \usepackage[none]{hyphenat} - -#+OPTIONS: H:20 num:20 -#+OPTIONS: author:nil - -[[file:../index.org][Back to main documentation]] - -* 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. - -* Specifying classes to render -:PROPERTIES: -:CUSTOM_ID: specifying-classes-to-render -:END: - -Normal Java application has immense complexity. In addition to code -that was directly written by particular project developers, lots of -functionality is typically added as frameworks or libraries to the -project. In addition there is significant Java standard library. - -Because JavaInspect uses reflection, it does not easily distinguish -between those. In normal situation you would rather want to visualize -only code that was developed specifically for your project and leave -frameworks like Spring etc. out. If you visualize all classes that are -possibly reachable from you project, you will easily get huge and -incomprehensible graph. - -JavaInspect can digest compiled Java classes in 2 modes: -1. Provide list of Jar files. Use *-j* option. -2. Provide list of filesystem directories that can be used as - classpath root. Use *-c* option. - -Currently JavaInspect uses following algorithm to add classes to -rendered graph: - -- All classes that were found in Jar files are added to graph by default. -- None of the classes that were found in filesystem directories are - added to the graph by default (unless explicitly referenced). (TODO: - for consistency it would be better to add them too by default) -- If whitelist is specified (*-w* option) everything that is not - matched by whitelist pattern(s) will be removed from the graph. -- If blacklist is specified (*-b* option) everything that is matched - by blacklist pattern(s) will be removed from the graph. -- Root classes can be specified using *-r* option. Root classes will - be added to the graph. JavaInspect will then try to recursively - discover all classes that were referenced by root class and add - those also to the graph. - -* Examples -:PROPERTIES: -:CUSTOM_ID: examples -:END: - -Visualize java Jar file. All classes. Hide orphaned classes: - -#+begin_src sh - javainspect \ - -j target/sixth-3d-*-SNAPSHOT.jar \ - -d doc/graphs/ \ - -n "all classes" \ - -t png -ho -#+end_src - - -Visualize java Jar file. All classes. Hide orphaned classes. Apply -whitelist: - -#+begin_src sh - javainspect \ - -j target/sixth-3d-*-SNAPSHOT.jar \ - -d doc/graphs/ \ - -n "GUI" \ - -t png \ - -w "eu.svjatoslav.sixth.e3d.gui.*" \ - -ho -#+end_src