Skip to content

Commit a7ae3eb

Browse files
committed
Generate reference documentation for the whole project.
1 parent 7b8b37b commit a7ae3eb

11 files changed

Lines changed: 282 additions & 219 deletions

.github/workflows/internal-environment-variables-reference-documentation.yml

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -28,9 +28,8 @@ jobs:
2828
token: ${{ secrets.WORKFLOW_GIT_ACCESS_TOKEN }}
2929

3030
- name: Generate environment variables reference document
31-
working-directory: scripts
3231
run: |
33-
./documentation/generateEnvironmentVariableReference.sh
32+
./scripts/documentation/generateEnvironmentVariableReference.sh
3433
3534
- name: Use git to detect changes in the regenerated document and set generated_document_changed
3635
run: git diff --quiet || echo "generated_document_changed=true" >> $GITHUB_ENV
@@ -43,7 +42,7 @@ jobs:
4342
uses: actions/upload-artifact@v6
4443
with:
4544
name: environment-variables-reference-document
46-
path: ./scripts/ENVIRONMENT_VARIABLES.md
45+
path: ./ENVIRONMENT_VARIABLES.md
4746
if-no-files-found: error
4847
retention-days: 5
4948

@@ -57,13 +56,13 @@ jobs:
5756
git config --global user.email "7671054+JohT@users.noreply.github.com"
5857
git fetch origin
5958
git status
60-
git add ./scripts/ENVIRONMENT_VARIABLES.md
59+
git add ./ENVIRONMENT_VARIABLES.md
6160
git status
6261
git commit -m "${{ env.CI_COMMIT_MESSAGE }}"
6362
git status
6463
git rebase --strategy-option=theirs origin/main --verbose
6564
git status
66-
git add ./scripts/ENVIRONMENT_VARIABLES.md
65+
git add ./ENVIRONMENT_VARIABLES.md
6766
git status
6867
git commit --amend --no-edit
6968
git status

.github/workflows/internal-scripts-reference-documentation.yml

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -28,9 +28,8 @@ jobs:
2828
token: ${{ secrets.WORKFLOW_GIT_ACCESS_TOKEN }}
2929

3030
- name: Generate scripts reference document
31-
working-directory: scripts
3231
run: |
33-
./documentation/generateScriptReference.sh
32+
./scripts/documentation/generateScriptReference.sh
3433
3534
- name: Use git to detect changes in the regenerated document and set generated_document_changed
3635
run: git diff --quiet || echo "generated_document_changed=true" >> $GITHUB_ENV
@@ -43,7 +42,7 @@ jobs:
4342
uses: actions/upload-artifact@v6
4443
with:
4544
name: scripts-reference-document
46-
path: ./scripts/SCRIPTS.md
45+
path: ./SCRIPTS.md
4746
if-no-files-found: error
4847
retention-days: 5
4948

@@ -57,13 +56,13 @@ jobs:
5756
git config --global user.email "7671054+JohT@users.noreply.github.com"
5857
git fetch origin
5958
git status
60-
git add ./scripts/SCRIPTS.md
59+
git add ./SCRIPTS.md
6160
git status
6261
git commit -m "${{ env.CI_COMMIT_MESSAGE }}"
6362
git status
6463
git rebase --strategy-option=theirs origin/main --verbose
6564
git status
66-
git add ./scripts/SCRIPTS.md
65+
git add ./SCRIPTS.md
6766
git status
6867
git commit --amend --no-edit
6968
git status

CHANGELOG.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -511,7 +511,7 @@ For all details see: https://github.com/JohT/code-graph-analysis-pipeline/releas
511511

512512
* Analyze static code structure, dependencies, metrics, ...
513513
* Fully automated [pipeline](./.github/workflows/public-analyze-code-graph.yml) from tool installation and artifact download to report generation
514-
* Runtime and library independent automation using [shell scripts](./scripts/SCRIPTS.md)
514+
* Runtime and library independent automation using [shell scripts](./SCRIPTS.md)
515515
* Comprehensive list of [Cypher queries](./cypher/CYPHER.md)
516516
* Example Analysis for [AxonFramework](https://github.com/AxonFramework/AxonFramework)
517517

ENVIRONMENT_VARIABLES.md

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
# Environment Variables Reference
2+
3+
This document serves as a reference for all environment variables that are supported by the script files.
4+
It provides a table listing each environment variable, its default value and its corresponding description provided as a inline comment.
5+
This file was generated with the script [appendEnvironmentVariables.sh](./scripts/documentation/appendEnvironmentVariables.sh) and [generateEnvironmentVariableReference.sh](./scripts/documentation/generateEnvironmentVariableReference.sh).
6+
7+
Environment Variable Name | Default | Description
8+
------------------------- | ------- | -----------
9+
REPORTS_DIRECTORY | reports |
10+
SCRIPTS_DIR | ${ANOMALY_DETECTION_SCRIPT_DIR}/../../scripts | Repository directory containing the shell scripts
11+
ANOMALY_DETECTION_FEATURE_CYPHER_DIR | ${ANOMALY_DETECTION_SCRIPT_DIR}/features |
12+
ANOMALY_DETECTION_QUERY_CYPHER_DIR | ${ANOMALY_DETECTION_SCRIPT_DIR}/queries |
13+
ANOMALY_DETECTION_LABEL_CYPHER_DIR | ${ANOMALY_DETECTION_SCRIPT_DIR}/labels |
14+
ANOMALY_DETECTION_SUMMARY_DIR | ${ANOMALY_DETECTION_SCRIPT_DIR}/summary | Contains everything (scripts, queries, templates) to create the Markdown summary report for anomaly detection
15+
MARKDOWN_INCLUDES_DIRECTORY | includes | Subdirectory that contains Markdown files to be included by the Markdown template for the report.
16+
ANOMALY_DETECTION_GRAPHS_DIR | ${ANOMALY_DETECTION_SCRIPT_DIR}/graphs | Contains everything (scripts, queries, templates) to create the Markdown summary report for anomaly detection
17+
VISUALIZATION_SCRIPTS_DIR | ${SCRIPTS_DIR}/visualization | Repository directory containing the shell scripts for visualization
18+
MARKDOWN_SCRIPTS_DIR | ${SCRIPTS_DIR}/markdown |
19+
EXTERNAL_DEPENDENCIES_QUERY_CYPHER_DIR | ${EXTERNAL_DEPENDENCIES_SCRIPT_DIR}/queries |
20+
EXTERNAL_DEPENDENCIES_SUMMARY_DIR | ${EXTERNAL_DEPENDENCIES_SCRIPT_DIR}/summary | Contains everything (scripts, queries, templates) to create the Markdown summary report for external dependencies
21+
INTERNAL_DEPENDENCIES_SUMMARY_DIR | ${INTERNAL_DEPENDENCIES_SCRIPT_DIR}/summary | Contains everything (scripts, templates) to create the Markdown summary report
22+
INTERNAL_DEPENDENCIES_GRAPHS_DIR | ${INTERNAL_DEPENDENCIES_SCRIPT_DIR}/graphs | Contains everything (scripts, queries) to create graph visualizations
23+
NEO4J_EDITION | community | Choose "community" or "enterprise"
24+
NEO4J_VERSION | 2026.01.4 |
25+
DATA_DIRECTORY | $( pwd -P )/data | Path where Neo4j writes its data to (outside tools dir)
26+
RUNTIME_DIRECTORY | $( pwd -P )/runtime | Path where Neo4j puts runtime data to (e.g. logs) (outside tools dir)
27+
NEO4J_HTTP_PORT | 7474 | Neo4j HTTP API port for executing queries
28+
NEO4J_HTTPS_PORT | 7473 | Neo4j HTTPS port for encrypted querying
29+
NEO4J_BOLT_PORT | 7687 | Neo4j's own "Bolt Protocol" port
30+
NEO4J_CONFIG_TEMPLATE | template-neo4j.conf | Name of the template file ("configuration" folder) for the Neo4j configuration. Defaults to "template-neo4j.conf".
31+
TOOLS_DIRECTORY | tools | Tools directory name used to detect the analysis workspace
32+
NEO4J_APOC_PLUGIN_VERSION | 2026.01.4 | Awesome Procedures On Cypher (APOC) Plugin version number. Version needs to be compatible to Neo4j and usually matches its version number.
33+
NEO4J_APOC_PLUGIN_EDITION | core | Awesome Procedures On Cypher (APOC) for Neo4j Plugin Edition (Neo4j v4.4.x "all", Neo4j >= v5 "core")
34+
NEO4J_APOC_PLUGIN_GITHUB | neo4j/apoc | Awesome Procedures On Cypher (APOC) for Neo4j Plugin GitHub User/Repository (Neo4j v4.4.x "neo4j-contrib/neo4j-apoc-procedures", Neo4j >= v5 "neo4j/apoc")
35+
NEO4J_GDS_PLUGIN_VERSION | 2.27.0 | Graph Data Science (GDS) Plugin Version 2.4.x of is compatible with Neo4j 5.x
36+
NEO4J_OPEN_GDS_PLUGIN_VERSION | 2.26.0 | Graph Data Science (GDS) Plugin Version 2.4.x of is compatible with Neo4j 5.x
37+
NEO4J_GDS_PLUGIN_EDITION | open | Graph Data Science (GDS) Plugin Edition: "open" for OpenGDS, "full" for the full version with Neo4j license
38+
ARTIFACTS_DIRECTORY | artifacts |
39+
SOURCE_DIRECTORY | source |
40+
PREPARE_CONDA_ENVIRONMENT | true | Wether to prepare a Python environment with Conda if needed (default, "true") or use an already prepared Conda environment ("false")
41+
JUPYTER_NOTEBOOK_DIRECTORY | ${SCRIPTS_DIR}/../jupyter | Repository directory containing the Jupyter Notebooks
42+
CONDA_ENVIRONMENT_FILE | ${JUPYTER_NOTEBOOK_DIRECTORY}/../conda-environment.yml | Conda (package manager for Python) environment file path
43+
CODEGRAPH_CONDA_ENVIRONMENT | codegraph | Name of the conda environment to use for code graph analysis
44+
USE_VIRTUAL_PYTHON_ENVIRONMENT_VENV | false | Use "venv" for virtual Python environments ("true") or use an already prepared (e.g. conda) environment (default, "false").
45+
PYTHON_ENVIRONMENT_FILE | ${ROOT_DIRECTORY}/requirements.txt | Pip (package manager for Python) environment file path
46+
REPORTS_SCRIPTS_DIRECTORY | reports | Working directory containing the generated reports
47+
REPORT_COMPILATIONS_SCRIPTS_DIRECTORY | compilations | Repository directory that contains scripts that execute selected report generation scripts
48+
SETTINGS_PROFILE_SCRIPTS_DIRECTORY | profiles | Repository directory that contains scripts containing settings
49+
LOG_GROUP_START | ::group:: | Prefix to start a log group. Defaults to GitHub Actions log group start command.
50+
LOG_GROUP_END | ::endgroup:: | Prefix to end a log group. Defaults to GitHub Actions log group end command.
51+
DOMAINS_DIRECTORY | ${SCRIPTS_DIR}/../domains |
52+
ARTIFACTS_CHANGE_DETECTION_HASH_FILE | artifactsChangeDetectionHash.txt | !DEPRECATED! Use CHANGE_DETECTION_HASH_FILE.
53+
CHANGE_DETECTION_HASH_FILE_PATH | ./${ARTIFACTS_DIRECTORY}/${CHANGE_DETECTION_HASH_FILE} | Default path of the file that contains the hash code of the file list for change detection. Can be overridden by a command line option.
54+
ENABLE_JUPYTER_NOTEBOOK_PDF_GENERATION | | Enable PDF generation for Jupyter Notebooks if set to any non empty value like "true" or disable it with "" or "false".
55+
JUPYTER_OUTPUT_FILE_POSTFIX | | e.g. "" (no postfix), ".nbconvert" or ".output"
56+
REPORTS_SCRIPT_DIR | ${SCRIPTS_DIR}/reports | Repository directory containing the report scripts
57+
NEO4J_HTTP_TRANSACTION_ENDPOINT | db/neo4j/tx/commit | Since Neo4j v5: "db/<name>/tx/commit", Neo4j v4: "db/data/transaction/commit"
58+
IMPORT_DIRECTORY | import |
59+
IMPORT_GIT_LOG_DATA_IF_SOURCE_IS_PRESENT | plugin | Select how to import git log data. Options: "none", "aggregated", "full" and "plugin". Default="plugin".
60+
JQASSISTANT_CLI_VERSION | 2.9.0 |
61+
JQASSISTANT_CLI_ARTIFACT | jqassistant-commandline-neo4jv5 |
62+
JQASSISTANT_CONFIG_TEMPLATE | template-neo4jv5-jqassistant-continue-on-error.yaml |
63+
programmingLanguage | Java | Set to default value "Java" if not set since it is optional
64+
NEO4J_INITIAL_PASSWORD | | Neo4j login password that was set to replace the temporary initial password
65+
DOMAINS_DIR | ${SCRIPTS_DIR}/../domains | Repository directory containing the domain scripts
66+
TYPESCRIPT_SCAN_HEAP_MEMORY | 4096 | Heap memory in megabytes for Typescript scanning with (Node.js process). Defaults to 4096 MB.
67+
JQASSISTANT_CLI_DOWNLOAD_URL | https://repo1.maven.org/maven2/com/buschmais/jqassistant/cli | Download URL for the jQAssistant CLI
68+
JQASSISTANT_CLI_DISTRIBUTION | distribution.zip | Neo4j v5 & v4: "distribution.zip"
69+
IGNORED_JARS_DIRECTORY | ./../ignored-jars | Directory to move the filtered out .jar files to

README.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ Curious? Explore the examples at [code-graph-analysis-examples](https://github.c
2626
- Anomaly detection powered by unsupervised machine learning and explainable AI
2727
- Graph structure visualization
2828
- Automated reference document generation
29-
- Runtime and library independent automation using [shell scripts](./scripts/SCRIPTS.md)
29+
- Runtime and library independent automation using [shell scripts](./SCRIPTS.md)
3030
- Tested on MacOS (zsh), Linux (bash) and Windows (Git Bash)
3131
- Comprehensive list of [Cypher queries](./cypher/CYPHER.md)
3232
- Example analysis for [AxonFramework](https://github.com/AxonFramework/AxonFramework)
@@ -194,7 +194,7 @@ The [Code Structure Analysis Pipeline](./.github/workflows/internal-java-code-an
194194

195195
## :gear: Script Reference
196196

197-
[SCRIPTS.md](./scripts/SCRIPTS.md) lists all shell scripts of this repository including their first comment line as a description. It can be generated as described in [Generate Script Reference](./COMMANDS.md#generate-script-reference).
197+
[SCRIPTS.md](./SCRIPTS.md) lists all shell scripts of this repository including their first comment line as a description. It can be generated as described in [Generate Script Reference](./COMMANDS.md#generate-script-reference).
198198

199199
## :mag: Cypher Query Reference
200200

@@ -203,7 +203,7 @@ The [Code Structure Analysis Pipeline](./.github/workflows/internal-java-code-an
203203
204204
## :globe_with_meridians: Environment Variable Reference
205205

206-
[ENVIRONMENT_VARIABLES.md](./scripts/ENVIRONMENT_VARIABLES.md) contains all environment variables that are supported by the scripts including default values and description. It can be generated as described in [Generate Environment Variable Reference](./COMMANDS.md#generate-environment-variable-reference).
206+
[ENVIRONMENT_VARIABLES.md](./ENVIRONMENT_VARIABLES.md) contains all environment variables that are supported by the scripts including default values and description. It can be generated as described in [Generate Environment Variable Reference](./COMMANDS.md#generate-environment-variable-reference).
207207

208208
## :closed_book: Change Log
209209

0 commit comments

Comments
 (0)