From de1d27e920655ae40b5a3beddc3d27d4f78e53d9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Annama=CC=81ria=20Koren?= Date: Fri, 4 Sep 2026 08:25:15 +0200 Subject: [PATCH 1/2] WIP: activate MD061 and MD044 --- .rumdl.toml | 35 +++++++++++++++++++++++++++++++++++ Taskfile.yml | 2 +- 2 files changed, 36 insertions(+), 1 deletion(-) create mode 100644 .rumdl.toml diff --git a/.rumdl.toml b/.rumdl.toml new file mode 100644 index 000000000..37afe2f0b --- /dev/null +++ b/.rumdl.toml @@ -0,0 +1,35 @@ +[global] +disable = ["MD035", "MD025", "MD012", "MD041", "MD045", "MD060", "MD051", "MD046", "MD024", "MD059", "MD077", "MD036", "MD013"] + +[MD007] +indent = 4 +style = "fixed" + +[MD030] +ul-multi = 1 +ul-single = 1 + +[MD033] +allowed-elements = ["a", "br", "cite", "details", "div", "figcaption", "figure", "img", "key", "name", "p", "param", "span", "summary", "connection", "tool", "code"] + +[MD061] +terms = [ + # Höflichkeitsfloskeln / Füllwörter + "please", "thanks", "thank you", + + # Kontraktionen: negiert + "don't", "doesn't", "didn't", "can't", "cannot", "won't", "isn't", "aren't", + "wasn't", "weren't", "hasn't", "haven't", "hadn't", "shouldn't", "wouldn't", + "couldn't", "mustn't", "needn't", + + # Kontraktionen: Verb + sein/haben/werden + "it's", "that's", "there's", "here's", "what's", "let's", + "you're", "we're", "they're", "you'll", "we'll", "they'll", "it'll", + "you've", "we've", "they've", "you'd", "we'd", "they'd", + + "CorporateMemory" +] +case-sensitive = true # Exact case matching (default) + +[MD044] +names = ["JavaScript", "GitHub", "Node.js", "TypeScript", "GitLab", "eccenca", "Corporate Memory", "eccenca Corporate Memory"] diff --git a/Taskfile.yml b/Taskfile.yml index a5ab440ee..bc73dce8c 100644 --- a/Taskfile.yml +++ b/Taskfile.yml @@ -11,7 +11,7 @@ vars: MATERIAL_TAG: 9.6.14 MATERIAL_INSIDER_TAG: 9.6.14-insiders-4.53.16 # the markdown linter command, used by format:fix:path and check:rumdl - RUMDL_CHECK: poetry run rumdl --config .markdownlint.jsonc check + RUMDL_CHECK: poetry run rumdl --config .rumdl.toml check # the default lint targets: the docs tree plus the top-level markdown files DOCS_PATHS: ./docs ./*.md From 798235370a5d8888009f506f87b83aeee1ca862f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Annama=CC=81ria=20Koren?= Date: Fri, 4 Sep 2026 10:29:04 +0200 Subject: [PATCH 2/2] fix MD061 and MD044 findings in hand-written docs, CMEM-8136 Resolve all MD061 (forbidden terms) and MD044 (proper name casing) findings in files that are not machine-generated: expand contractions, drop politeness fillers, correct GitHub/GitLab/JavaScript/TypeScript/eccenca/Corporate Memory. Two config decisions in .rumdl.toml: - Drop "cannot" from [MD061].terms. It is not a contraction but the standard spelling, and it is what "can't" has to be corrected to. Keeping it would have forced 40 correct sentences into the awkward "can not". - List technical identifiers at the top of [MD044].names, before the brand names they contain. MD044 resolves overlaps by the longer match, so this stops rumdl --fix from destroying Material icon shortcodes (icon: material/github, :simple-gitlab:), the gitlab.eccenca.com hostname and LOGGING_LEVEL_COM_ECCENCA_* environment variables. Add tests/test_rumdl_md044_allowlist.py to pin the allowlist down: the protected identifiers must survive rumdl --fix, and the rule must keep reporting the same names in running text. Files carrying a "generated - do not change manually" marker are left untouched; the 42 findings remaining there need fixes in their generators. Note that the graph-insights files declared generated in _README.md carry no inline marker of their own. Also correct proper names inside link text, which MD044 does not inspect. --- .rumdl.toml | 18 ++- CONTRIBUTING.md | 4 +- README.md | 2 +- .../index.md | 2 +- .../invocation/github-action/index.md | 12 +- .../invocation/gitlab-pipeline/index.md | 14 +- .../invocation/index.md | 4 +- .../scripting-with-cmemc/index.md | 2 +- .../troubleshooting-and-caveats/index.md | 2 +- .../index.md | 4 +- docs/automate/continuous-integration/index.md | 4 +- .../index.md | 4 +- docs/build/mapping-creator/index.md | 2 +- docs/build/snowflake-tutorial/index.md | 2 +- .../define-the-interfaces/index.md | 14 +- .../index.md | 6 +- .../link-IDS-event-to-KG-via-cmem/index.md | 4 +- .../consuming-graphs-with-redash/index.md | 2 +- .../configuration/caveats/index.md | 2 +- .../configuration/dataintegration/index.md | 2 +- .../explore/dataplatform/application-full.md | 1 + .../dataplatform/application-graphdb-full.md | 2 + .../dataplatform/application-http-full.md | 2 + .../dataplatform/application-inmemory-full.md | 2 + .../dataplatform/application-oauth-full.md | 2 + .../dataplatform/application-virtuoso-full.md | 2 + .../configuration/graphinsights/index.md | 6 +- .../configuration/keycloak/index.md | 2 +- .../installation/migrating-stores/index.md | 2 +- .../scenario-local-installation/index.md | 2 +- .../requirements/index.md | 2 +- docs/develop/cmemc-scripts/index.md | 2 +- docs/develop/python-plugins/setup/index.md | 2 +- docs/explore-and-author/companion/index.md | 8 +- .../with-your-sandbox/index.md | 2 +- .../corporate-memory-20-06/index.md | 4 +- .../corporate-memory-20-12/index.md | 2 +- .../corporate-memory-21-02/index.md | 2 +- .../corporate-memory-21-04/index.md | 4 +- .../corporate-memory-21-11/index.md | 6 +- .../corporate-memory-22-1/index.md | 2 +- .../corporate-memory-23-1/index.md | 2 +- .../corporate-memory-23-3/index.md | 2 +- .../corporate-memory-24-1/index.md | 2 +- .../corporate-memory-24-2/index.md | 2 +- .../corporate-memory-24-3/index.md | 2 +- tests/test_rumdl_md044_allowlist.py | 150 ++++++++++++++++++ 47 files changed, 250 insertions(+), 75 deletions(-) create mode 100644 tests/test_rumdl_md044_allowlist.py diff --git a/.rumdl.toml b/.rumdl.toml index 37afe2f0b..fcabe7526 100644 --- a/.rumdl.toml +++ b/.rumdl.toml @@ -18,7 +18,9 @@ terms = [ "please", "thanks", "thank you", # Kontraktionen: negiert - "don't", "doesn't", "didn't", "can't", "cannot", "won't", "isn't", "aren't", + # "cannot" ist bewusst nicht gelistet: das ist die Standardschreibweise, + # keine Kontraktion - und damit das Ziel der Korrektur von "can't". + "don't", "doesn't", "didn't", "can't", "won't", "isn't", "aren't", "wasn't", "weren't", "hasn't", "haven't", "hadn't", "shouldn't", "wouldn't", "couldn't", "mustn't", "needn't", @@ -32,4 +34,16 @@ terms = [ case-sensitive = true # Exact case matching (default) [MD044] -names = ["JavaScript", "GitHub", "Node.js", "TypeScript", "GitLab", "eccenca", "Corporate Memory", "eccenca Corporate Memory"] +names = [ + # Technische Bezeichner zuerst: laengere Treffer haben Vorrang und verhindern + # damit False Positives fuer die Markennamen weiter unten + # (Material-Icon-Shortcodes, Hostnamen, Umgebungsvariablen). + "material/github", "material/gitlab", + "material-github", "material-gitlab", + "simple-github", "simple-gitlab", + "gitlab.eccenca.com", + "COM_ECCENCA", + + # Markennamen und Schreibweisen + "JavaScript", "GitHub", "Node.js", "TypeScript", "GitLab", "eccenca", "Corporate Memory", "eccenca Corporate Memory" +] diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6f0de9241..d52c12133 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,6 @@ # Contributing -👍🎉 First off, thanks for taking the time to contribute! 🎉👍 +👍🎉 First off, we appreciate you taking the time to contribute! 🎉👍 The following is a set of guidelines for contributing to the eccenca Corporate Memory documentation project. @@ -96,7 +96,7 @@ Have a look at the [mkdocs-material documentation](https://squidfunk.github.io/m ## Icons -Where possible, please use icons as described on [the material for mkdocs documention](https://squidfunk.github.io/mkdocs-material/reference/icons-emojis/). +Where possible, use icons as described on [the material for mkdocs documention](https://squidfunk.github.io/mkdocs-material/reference/icons-emojis/). On this page is search function for icons available as well. ## Admonitions diff --git a/README.md b/README.md index 628d3e310..639a51783 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ Shared repository of the eccenca Corporate Memory documentation. | `main` | [https://dev.documentation.eccenca.com](https://dev.documentation.eccenca.com) | | `published` | [https://documentation.eccenca.com](https://documentation.eccenca.com) | -If you consider to contribute to this project, please have a look on [CONTRIBUTING.md](https://github.com/eccenca/documentation.eccenca.com/blob/main/CONTRIBUTING.md) +If you consider to contribute to this project, have a look on [CONTRIBUTING.md](https://github.com/eccenca/documentation.eccenca.com/blob/main/CONTRIBUTING.md) ## License diff --git a/docs/automate/cmemc-command-line-interface/configuration/getting-credentials-from-external-processes/index.md b/docs/automate/cmemc-command-line-interface/configuration/getting-credentials-from-external-processes/index.md index 6244eb7dc..5576dbc84 100644 --- a/docs/automate/cmemc-command-line-interface/configuration/getting-credentials-from-external-processes/index.md +++ b/docs/automate/cmemc-command-line-interface/configuration/getting-credentials-from-external-processes/index.md @@ -28,7 +28,7 @@ export OAUTH_CLIENT_SECRET="...secret..." cmemc graph list ``` -In the context of a CI/CD pipeline, e.g., on github, these credentials can be taken from the repository secrets: +In the context of a CI/CD pipeline, e.g., on GitHub, these credentials can be taken from the repository secrets: ``` yaml jobs: diff --git a/docs/automate/cmemc-command-line-interface/invocation/github-action/index.md b/docs/automate/cmemc-command-line-interface/invocation/github-action/index.md index 83ac5366b..1f07e7c72 100644 --- a/docs/automate/cmemc-command-line-interface/invocation/github-action/index.md +++ b/docs/automate/cmemc-command-line-interface/invocation/github-action/index.md @@ -1,16 +1,16 @@ --- -title: "cmemc: Using Github Actions" +title: "cmemc: Using GitHub Actions" icon: material/github tags: - Automate - cmemc --- -# Using Github Actions +# Using GitHub Actions ## Introduction -[Github Actions](https://docs.github.com/en/actions) allow for the automation and execution of workflows based on pushes, merge requests and other trigger events to your git repository. -In order to control eccenca Corporate Memory instances from within Github Action based workflows, you need to provide cmemc as well as credentials for your instance to the workflow. +[GitHub Actions](https://docs.github.com/en/actions) allow for the automation and execution of workflows based on pushes, merge requests and other trigger events to your git repository. +In order to control eccenca Corporate Memory instances from within GitHub Action based workflows, you need to provide cmemc as well as credentials for your instance to the workflow. ## Runner Provisioning @@ -34,7 +34,7 @@ Adding the above to your workflow yaml description will provide a cmemc command ## Credentials and Usage Since we should never save credentials in your repository, we need to provide them as an encrypted secret managed outside of the repository. -Github provides you with an [Encrypted Secrets](https://docs.github.com/en/actions/security-guides/encrypted-secrets) interface where you can add secrets for your repository, which in turn can be used in your workflows. +GitHub provides you with an [Encrypted Secrets](https://docs.github.com/en/actions/security-guides/encrypted-secrets) interface where you can add secrets for your repository, which in turn can be used in your workflows. Given the following workflow step, you need to add `MY_CMEM_BASE_URI`, `MY_OAUTH_GRANT_TYPE`, `MY_OAUTH_CLIENT_ID` and `MY_OAUTH_CLIENT_SECRET` as encrypted secrets to your repository: @@ -56,7 +56,7 @@ The above snippet also demonstrates how you can map your encrypted secrets to [c ## Example Project -The Github project [eccenca/cmemc-workflow](https://github.com/eccenca/cmemc-workflow) provides an [example workflow description](https://github.com/eccenca/cmemc-workflow/blob/main/.github/workflows/cmemc.yml) which uses cmemc to import a graph, count the triples and removes the graph afterwards. +The GitHub project [eccenca/cmemc-workflow](https://github.com/eccenca/cmemc-workflow) provides an [example workflow description](https://github.com/eccenca/cmemc-workflow/blob/main/.github/workflows/cmemc.yml) which uses cmemc to import a graph, count the triples and removes the graph afterwards. Here is an example output: ![Example workflow output](example-workflow-output.png "Example workflow output") diff --git a/docs/automate/cmemc-command-line-interface/invocation/gitlab-pipeline/index.md b/docs/automate/cmemc-command-line-interface/invocation/gitlab-pipeline/index.md index 7eadca577..b07a3bd2a 100644 --- a/docs/automate/cmemc-command-line-interface/invocation/gitlab-pipeline/index.md +++ b/docs/automate/cmemc-command-line-interface/invocation/gitlab-pipeline/index.md @@ -1,20 +1,20 @@ --- -title: "cmemc: Using Gitlab Pipelines" +title: "cmemc: Using GitLab Pipelines" icon: material/gitlab tags: - Automate - cmemc --- -# Using Gitlab Pipelines +# Using GitLab Pipelines ## Introduction -[Gitlab CI/CD](https://docs.gitlab.com/ee/topics/build_your_application.html) allows for the automation and execution of workflows based on pushes, merge requests and other trigger events to your git repository. -In order to control eccenca Corporate Memory instances from within Gitlab CI/CD based workflows you need to provide cmemc and the credentials for your instance to the Gitlab CI/CD pipeline. +[GitLab CI/CD](https://docs.gitlab.com/ee/topics/build_your_application.html) allows for the automation and execution of workflows based on pushes, merge requests and other trigger events to your git repository. +In order to control eccenca Corporate Memory instances from within GitLab CI/CD based workflows you need to provide cmemc and the credentials for your instance to the GitLab CI/CD pipeline. ## Runner Provisioning -In order to use cmemc in Gitlab pipelines you can use the [cmemc docker image](../docker-image/index.md). +In order to use cmemc in GitLab pipelines you can use the [cmemc docker image](../docker-image/index.md). ```yaml title="Partial .gitlab-ci.yml showing cmemc provisioning" test: @@ -30,7 +30,7 @@ Adding the above to your pipeline description will provide a cmemc command which ## Credentials and Usage Since we should never commit credentials in your repository, we need to provide them as an encrypted secret managed outside of the repository. -You can add [CI/CD variables](https://docs.gitlab.com/ee/ci/variables/#add-a-cicd-variable-to-a-project) to a project’s settings directly in Gitlab. +You can add [CI/CD variables](https://docs.gitlab.com/ee/ci/variables/#add-a-cicd-variable-to-a-project) to a project’s settings directly in GitLab. Given the following pipeline step, you need to add `MY_CMEM_BASE_URI`, `MY_OAUTH_GRANT_TYPE`, `MY_OAUTH_CLIENT_ID` and `MY_OAUTH_CLIENT_SECRET` as encrypted secrets to your repository: @@ -57,7 +57,7 @@ The above snippet also demonstrates how you can map your project variables to [c ## Example Project -The Github project [eccenca/cmemc-workflow](https://github.com/eccenca/cmemc-workflow) provides an [example gitlab pipeline description](https://github.com/eccenca/cmemc-workflow/blob/main/.gitlab-ci.yml) which uses cmemc to import a graph, count the triples and removes the graph afterwards. +The GitHub project [eccenca/cmemc-workflow](https://github.com/eccenca/cmemc-workflow) provides an [example GitLab pipeline description](https://github.com/eccenca/cmemc-workflow/blob/main/.gitlab-ci.yml) which uses cmemc to import a graph, count the triples and removes the graph afterwards. Here is an example output: ![Example pipeline output](example-pipeline-output.png "Example pipeline output") diff --git a/docs/automate/cmemc-command-line-interface/invocation/index.md b/docs/automate/cmemc-command-line-interface/invocation/index.md index bdf6f2e96..190c19532 100644 --- a/docs/automate/cmemc-command-line-interface/invocation/index.md +++ b/docs/automate/cmemc-command-line-interface/invocation/index.md @@ -14,9 +14,9 @@ Besides the plain ad-hoc invocation from a users terminal, the following recipes - :material-docker: Executing cmemc as a [Docker Container](docker-image/index.md). -- :material-github: Running cmemc jobs as part of [Github Actions](github-action/index.md). +- :material-github: Running cmemc jobs as part of [GitHub Actions](github-action/index.md). -- :material-gitlab: Running cmemc jobs as part of [Gitlab Pipelines](gitlab-pipeline/index.md). +- :material-gitlab: Running cmemc jobs as part of [GitLab Pipelines](gitlab-pipeline/index.md). - :eccenca-application-queries: Preparing [SPARQL Scripts](sparql-scripts/index.md) to fetch data from your Knowledge Graphs. diff --git a/docs/automate/cmemc-command-line-interface/scripting-with-cmemc/index.md b/docs/automate/cmemc-command-line-interface/scripting-with-cmemc/index.md index eaf62d9f0..1648fba4a 100644 --- a/docs/automate/cmemc-command-line-interface/scripting-with-cmemc/index.md +++ b/docs/automate/cmemc-command-line-interface/scripting-with-cmemc/index.md @@ -167,4 +167,4 @@ Refer to [Environment-based Configuration](../configuration/environment-based-co - [Workflow Execution and Orchestration](../workflow-execution-and-orchestration/index.md) - a complete example script which starts workflows in parallel and waits for the results. - [Backup and Restore](../backup-and-restore/index.md) - creating and restoring backup artifacts with cmemc. -- [Using Gitlab Pipelines](../invocation/gitlab-pipeline/index.md) and [Using Github Actions](../invocation/github-action/index.md) - running cmemc on a build server. +- [Using GitLab Pipelines](../invocation/gitlab-pipeline/index.md) and [Using GitHub Actions](../invocation/github-action/index.md) - running cmemc on a build server. diff --git a/docs/automate/cmemc-command-line-interface/troubleshooting-and-caveats/index.md b/docs/automate/cmemc-command-line-interface/troubleshooting-and-caveats/index.md index 6622577f1..f3d989ed6 100644 --- a/docs/automate/cmemc-command-line-interface/troubleshooting-and-caveats/index.md +++ b/docs/automate/cmemc-command-line-interface/troubleshooting-and-caveats/index.md @@ -54,7 +54,7 @@ $ cmemc -c my-cmem project import my-project.zip my-project Import file my-project.zip to project my-project ... 504 Server Error: Gateway Time-out for url: https://my-cmem/dataintegration/workspace/projects ``` -This can have multiple reasons - please check in the following order: +This can have multiple reasons - check in the following order: - `application.yaml` of DataIntegration - reverse proxy configuration diff --git a/docs/automate/cmemc-command-line-interface/workflow-execution-and-orchestration/index.md b/docs/automate/cmemc-command-line-interface/workflow-execution-and-orchestration/index.md index 2cbb179d9..5869505ba 100644 --- a/docs/automate/cmemc-command-line-interface/workflow-execution-and-orchestration/index.md +++ b/docs/automate/cmemc-command-line-interface/workflow-execution-and-orchestration/index.md @@ -44,7 +44,7 @@ $ cmemc workflow execute cmem:my-workflow --wait cmem:my-workflow ... Started ... Finished (Finished in 32.931s, just now) ``` -For a reference of the `workflow execute` command, please have a look at the [Command Reference](../command-reference/index.md) or the command-specific help (`cmemc workflow execute --help`). +For a reference of the `workflow execute` command, have a look at the [Command Reference](../command-reference/index.md) or the command-specific help (`cmemc workflow execute --help`). ## Retrieve Status Information @@ -80,7 +80,7 @@ $ cmemc workflow status cmem:my-workflow --raw } ``` -For a reference of the `workflow status` command, please have a look at the [Command Reference](../command-reference/index.md) or the command-specific help (`cmemc workflow status --help`). +For a reference of the `workflow status` command, have a look at the [Command Reference](../command-reference/index.md) or the command-specific help (`cmemc workflow status --help`). ## Serial Execution diff --git a/docs/automate/continuous-integration/index.md b/docs/automate/continuous-integration/index.md index c7780dc01..8ac6c84a6 100644 --- a/docs/automate/continuous-integration/index.md +++ b/docs/automate/continuous-integration/index.md @@ -33,8 +33,8 @@ The following pages provide recipes for different CI/CD solutions:
-- :material-github: [Github Actions](../cmemc-command-line-interface/invocation/github-action/index.md) +- :material-github: [GitHub Actions](../cmemc-command-line-interface/invocation/github-action/index.md) -- :material-gitlab: [Gitlab Pipelines](../cmemc-command-line-interface/invocation/gitlab-pipeline/index.md) +- :material-gitlab: [GitLab Pipelines](../cmemc-command-line-interface/invocation/gitlab-pipeline/index.md)
diff --git a/docs/build/loading-jdbc-datasets-incrementally/index.md b/docs/build/loading-jdbc-datasets-incrementally/index.md index 3461908b3..7e95df2e6 100644 --- a/docs/build/loading-jdbc-datasets-incrementally/index.md +++ b/docs/build/loading-jdbc-datasets-incrementally/index.md @@ -67,7 +67,7 @@ To incrementally extract data in Corporate Memory, we need to store the informat ### To find the JDBC endpoint IRI 1. Visit the **Exploration** Tab of Corporate Memory -2. Select in Graph (top left) your project, which starts with "**CMEM DI Project** ... " (if you cannot see it, you might not have the necessary access rights. In this case, please contact your administrator) +2. Select in Graph (top left) your project, which starts with "**CMEM DI Project** ... " (if you cannot see it, you might not have the necessary access rights. In this case, contact your administrator) 3. Select in Navigation (bottom left): **functions_Plugins_Jdbc** 4. Select the previously created JDBC endpoint (in our example: "Services Table (JDBC)" 5. Press the **Turtle** tab inside your JDBC endpoint view (right) @@ -182,7 +182,7 @@ Finally, we can build a Workflow which demonstrates how each step works. We compose the SQL query based on the OFFSET and LIMIT information in our Metadata Graph. This SQL query will be used to configure the sourceQuery of the JDBC endpoint. Next, we do a "regular" transformation of data from a JDBC endpoint to RDF. -As this step was omitted here, please feel free to read how this Transformation can be built here: [Lift data from tabular data such as CSV, XSLX or database tables](../../build/lift-data-from-tabular-data-such-as-csv-xslx-or-database-tables/index.md). +As this step was omitted here, feel free to read how this Transformation can be built here: [Lift data from tabular data such as CSV, XSLX or database tables](../../build/lift-data-from-tabular-data-such-as-csv-xslx-or-database-tables/index.md). As a final step, we use our SPARQL update query to select the max service ID in our Knowledge Graph and update the RDF Triples in our Metadata Graph accordingly. ![Workflow using config part for incremental data loading](incr-jdbc-complete-wf.png){ class="bordered" } diff --git a/docs/build/mapping-creator/index.md b/docs/build/mapping-creator/index.md index 23d4b9d50..28cbebbaa 100644 --- a/docs/build/mapping-creator/index.md +++ b/docs/build/mapping-creator/index.md @@ -120,7 +120,7 @@ Accept (:octicons-thumbsup-16:) or reject (:octicons-thumbsdown-16:) each sugges ![Smart Class Suggestions](mapping-creator-class-suggestion.png){ class="bordered" } -If you haven't selected a target class yet, the AI will suggest classes from the selected vocabularies that best fit your source data. +If you have not selected a target class yet, the AI will suggest classes from the selected vocabularies that best fit your source data. Alternatively, you can search for classes manually by typing text into the search field. Hover over the wand icon for each suggestion to understand why this class has been recommended. diff --git a/docs/build/snowflake-tutorial/index.md b/docs/build/snowflake-tutorial/index.md index 3f898c32c..8f71143e0 100644 --- a/docs/build/snowflake-tutorial/index.md +++ b/docs/build/snowflake-tutorial/index.md @@ -20,7 +20,7 @@ This connection allows organizations to store and manage large amounts of data i By integrating Snowflake with eccenca Corporate Memory, organizations can achieve a centralized and unified data management system that allows them to gain a complete and accurate view of all their data assets. This integration enables organizations to make informed decisions, improve their business processes, and drive growth and innovation by leveraging their data assets. -This tutorial contains the following step-by-step instructions to connect the Snowflake data-warehouse with eccenca corporate memory: +This tutorial contains the following step-by-step instructions to connect the Snowflake data-warehouse with eccenca Corporate Memory: - [1. Create a database in Snowflake](#1-create-a-database-in-snowflake) - [2. Create a project in eccenca Corporate Memory](#2-create-a-project-in-eccenca-corporate-memory) diff --git a/docs/build/tutorial-how-to-link-ids-to-osint/define-the-interfaces/index.md b/docs/build/tutorial-how-to-link-ids-to-osint/define-the-interfaces/index.md index 23fe2db7c..4f5ac17fd 100644 --- a/docs/build/tutorial-how-to-link-ids-to-osint/define-the-interfaces/index.md +++ b/docs/build/tutorial-how-to-link-ids-to-osint/define-the-interfaces/index.md @@ -37,17 +37,17 @@ Here, the figure 3 is nice but before this first schema during the project, ther ## Technical feasibility with the available information -It's not really technical to check if the data is available or not, but without technical knowledge, it's hard to evaluate the difficulty to link each id to their instance in your RDF knowledge graph. -In this tutorial, we learn to use Corporate Memory of Eccenca to transform these IDs to IRI to import properly these ID with the other data necessary to build these interface. +It is not really technical to check if the data is available or not, but without technical knowledge, it is hard to evaluate the difficulty to link each id to their instance in your RDF knowledge graph. +In this tutorial, we learn to use Corporate Memory of eccenca to transform these IDs to IRI to import properly these ID with the other data necessary to build these interface. -After research and one meeting with analysts, we have chosen the datasets of Mitre Attack, the datasets of IoC rules (Sigma and Hayabusa) in Github and of course, the IoCs data already in the Splunk indexes. +After research and one meeting with analysts, we have chosen the datasets of Mitre Attack, the datasets of IoC rules (Sigma and Hayabusa) in GitHub and of course, the IoCs data already in the Splunk indexes.
![Figure 5. Define the information available in alerts of IDS and in OSINT to link these information.](alert_data_of_ioc.png)
Figure 5. Define the information available in alerts of IDS and in OSINT to link these information.
-The Splunk indexes of IoCs are selected by the analysts in the dashboard via the component [multiselect input](https://docs.splunk.com/Documentation/Splunk/9.0.5/Viz/FormEditor#Multiselect) in the form part of dashboard (the form part inits other Splunk tokens). We have choosen the IDs to link these data and the figure 5 resumes how we are going to link these data via Corporate Memory of Eccenca. +The Splunk indexes of IoCs are selected by the analysts in the dashboard via the component [multiselect input](https://docs.splunk.com/Documentation/Splunk/9.0.5/Viz/FormEditor#Multiselect) in the form part of dashboard (the form part inits other Splunk tokens). We have choosen the IDs to link these data and the figure 5 resumes how we are going to link these data via Corporate Memory of eccenca. ## Understand the base of Splunk dashboards @@ -157,11 +157,11 @@ WHERE { ## Technical feasibility with the Splunk dashboard -During our project, we have implemented the SPARQL command necessary to execute a SPARQL query in a SPL query but also several scripts to extend the panels of dashboard. For example, these are problems to print a HTML text and open a external Web page in a dashboard. Before starting a knowledge graph, we need to know if we have to work with a specific syntax in output for Splunk. So, we have searched the simplest solution to print the HTML literal in our knowledge graph with their links. We found it and implemented simple Javascript scripts to resolve these problems. These scripts are imported via the header of dashboard XML and called in the XML of static table panel. You can see the final dashboard with the Mitre description in HTML (the Mitre in these datasets uses Markdown but we show how convert Markdown link to HTML). We give you these scripts in your [Linked Data App](../link-IDS-event-to-KG/eccenca_commands.tar.gz) ([tutorial page](../link-IDS-event-to-KG/index.md)). +During our project, we have implemented the SPARQL command necessary to execute a SPARQL query in a SPL query but also several scripts to extend the panels of dashboard. For example, these are problems to print a HTML text and open a external Web page in a dashboard. Before starting a knowledge graph, we need to know if we have to work with a specific syntax in output for Splunk. So, we have searched the simplest solution to print the HTML literal in our knowledge graph with their links. We found it and implemented simple JavaScript scripts to resolve these problems. These scripts are imported via the header of dashboard XML and called in the XML of static table panel. You can see the final dashboard with the Mitre description in HTML (the Mitre in these datasets uses Markdown but we show how convert Markdown link to HTML). We give you these scripts in your [Linked Data App](../link-IDS-event-to-KG/eccenca_commands.tar.gz) ([tutorial page](../link-IDS-event-to-KG/index.md)).
-![Figure 6. With an extern Javascript script, static tables support HTML and the user can open.](../link-IDS-event-to-KG/demo_ld.png) -
Figure 6. With an extern Javascript script, static tables support HTML and the user can open.
+![Figure 6. With an extern JavaScript script, static tables support HTML and the user can open.](../link-IDS-event-to-KG/demo_ld.png) +
Figure 6. With an extern JavaScript script, static tables support HTML and the user can open.
## Conclusion: starting to specify the necessary RDF models for these interfaces diff --git a/docs/build/tutorial-how-to-link-ids-to-osint/lift-data-from-YAML-data-of-hayabusa-sigma/index.md b/docs/build/tutorial-how-to-link-ids-to-osint/lift-data-from-YAML-data-of-hayabusa-sigma/index.md index ec1c1fa19..212581087 100644 --- a/docs/build/tutorial-how-to-link-ids-to-osint/lift-data-from-YAML-data-of-hayabusa-sigma/index.md +++ b/docs/build/tutorial-how-to-link-ids-to-osint/lift-data-from-YAML-data-of-hayabusa-sigma/index.md @@ -11,7 +11,7 @@ Here, we are working with the Hayabusa/Sigma rules available via GitHub: - [https://github.com/Yamato-Security/hayabusa-rules](https://github.com/Yamato-Security/hayabusa-rules) - [https://github.com/SigmaHQ/sigma](https://github.com/Yamato-Security/hayabusa-rules) -The problem of interoperability, here, is the YAML format of files, their random position in their folders in their Github projets. Moreover, the same rule can exist in different projects but in this tutorial, we will not fix this problem and we consider the IRI rule is their Web address. In Corporate Memory, we would fix that with the Linked Tool, we will study this tool in a next part of this tutorial. +The problem of interoperability, here, is the YAML format of files, their random position in their folders in their GitHub projets. Moreover, the same rule can exist in different projects but in this tutorial, we will not fix this problem and we consider the IRI rule is their Web address. In Corporate Memory, we would fix that with the Linked Tool, we will study this tool in a next part of this tutorial. To build this knowledge graph of rules, we need to: @@ -24,7 +24,7 @@ To build this knowledge graph of rules, we need to: The YAML syntax is used to define each rule and there is one file by rule. -Corporate Memory doesn't support YAML (for the moment) but you can convert the files in JSON with this bash where you need to install git and [yq](https://github.com/mikefarah/yq). +Corporate Memory does not support YAML (for the moment) but you can convert the files in JSON with this bash where you need to install git and [yq](https://github.com/mikefarah/yq). Moreover, we use yq to add the field `rulePath` in each file with their paths in their repositories to have the possibility to rebuild their positions on the Web and so allowing the analyst to click directly on this link to read the details and may be, modify this rule. @@ -153,7 +153,7 @@ This new transformer are building the following RDF model for your use case: ![](23-1-success-workflow.png) - And don't forget to allow the replacement of JSON dataset because it allows to replace this specific JSON by all other rules during the execution of this worflow. + And do not forget to allow the replacement of JSON dataset because it allows to replace this specific JSON by all other rules during the execution of this worflow. ![](23-1-workflow-allow-replacement.png) diff --git a/docs/build/tutorial-how-to-link-ids-to-osint/link-IDS-event-to-KG-via-cmem/index.md b/docs/build/tutorial-how-to-link-ids-to-osint/link-IDS-event-to-KG-via-cmem/index.md index cc9e47626..542cad9e7 100644 --- a/docs/build/tutorial-how-to-link-ids-to-osint/link-IDS-event-to-KG-via-cmem/index.md +++ b/docs/build/tutorial-how-to-link-ids-to-osint/link-IDS-event-to-KG-via-cmem/index.md @@ -88,7 +88,7 @@ With these interfaces to manage and calculate different investigations with diff ## Manage the graphs of your application -A knowledge graph in Corporate Memory is a set of named RDF graphs. Each named graph can be managed and each named graph can have missions very different. In this PoC, when a new investigation is created, the app creates in first the named graph "investigation" to link all the other tempory named graphs for this investigation with the property "owl:imports". So, when an analyst want to delete an investigation, the app can find all the tempory graphs of this investigation and can delete all its tempory graphs simply. Moreover, the analyst can request with SPARQL all these tempory graphs via one named graph "investigation" (thanks to "owl:imports"), so the complexity of tempory graphs is invisible for the final user. +A knowledge graph in Corporate Memory is a set of named RDF graphs. Each named graph can be managed and each named graph can have missions very different. In this PoC, when a new investigation is created, the app creates in first the named graph "investigation" to link all the other tempory named graphs for this investigation with the property "owl:imports". So, when an analyst want to delete an investigation, the app can find all the tempory graphs of this investigation and can delete all its tempory graphs simply. Moreover, the analyst can request with SPARQL all these tempory graphs via one named graph "investigation" (due to "owl:imports"), so the complexity of tempory graphs is invisible for the final user. An error of novices is to save all the triples of data in input and their inferences in the same graph. For each upload of facts, each calculated inference, etc, you need to save their triples in its own named graph because during the life of data (and the development), you want to restore easily one named graph without re-building all the other graphs. @@ -178,7 +178,7 @@ In the previous chapter, you explain the role of token "source_x" to create a ne ``` -Here the example is simple with one external token, but when you have several external tokens in the token "source_x", there are often problems to generate a complet SPL query (to check the SPL query, you need to use the Javascript console via the Javascript "investigation.js" to read the final SPL queries in the tokens "source_x"). +Here the example is simple with one external token, but when you have several external tokens in the token "source_x", there are often problems to generate a complet SPL query (to check the SPL query, you need to use the JavaScript console via the JavaScript "investigation.js" to read the final SPL queries in the tokens "source_x"). You can add in your dashboard several tokens "source_1", "source_2", "source_3", etc. Each source generates a part of final bash script where a curl command requests the Splunk API and a CMEMC command executes the specified worflow via its ID in the token. With this method, the analyst is free to import any Splunk data and choose any CMEM workflow according to these data. The SPL queries are executed by the Splunk API (via curl), so the analyst is free to use all commands supported in Splunk to select the data. For example, with low-level investigation, these SPL queries contains also the selected period by the analyst to limit the quantity of data to import. diff --git a/docs/consume/consuming-graphs-with-redash/index.md b/docs/consume/consuming-graphs-with-redash/index.md index 331f716ff..697b82db9 100644 --- a/docs/consume/consuming-graphs-with-redash/index.md +++ b/docs/consume/consuming-graphs-with-redash/index.md @@ -34,7 +34,7 @@ This configuration screen basically clones the basic configuration of [cmemc](.. Once you added a eccenca Corporate Memory data source to Redash, you can create queries, configure visualisation widgets based on the query results, and combine these widgets as dashboards. -To get familiar with Redash, please have a look at the Redash user guide, especially the [Getting Started](https://redash.io/help/user-guide/getting-started) page. +To get familiar with Redash, have a look at the Redash user guide, especially the [Getting Started](https://redash.io/help/user-guide/getting-started) page. !!! Info diff --git a/docs/deploy-and-configure/configuration/caveats/index.md b/docs/deploy-and-configure/configuration/caveats/index.md index 322f2b9d2..51422a9c9 100644 --- a/docs/deploy-and-configure/configuration/caveats/index.md +++ b/docs/deploy-and-configure/configuration/caveats/index.md @@ -32,7 +32,7 @@ Hence, DI workflow execution will not proceed even though the update went throug Similar problems can occur between the connection between Explore backend (DataPlatform) and GraphDB. In addition to the hints in the next sections you can always change the TCP keep-alive of the system hosting the containers. -However in cloud environments this often isn't practical. In Debian based Linux distribution you have to edit `/etc/sysctl.conf`. +However in cloud environments this often is not practical. In Debian based Linux distribution you have to edit `/etc/sysctl.conf`. But be advised, only do this, if you are aware of the risks. ``` unixconfig diff --git a/docs/deploy-and-configure/configuration/dataintegration/index.md b/docs/deploy-and-configure/configuration/dataintegration/index.md index 61e5bac69..34dfb74b6 100644 --- a/docs/deploy-and-configure/configuration/dataintegration/index.md +++ b/docs/deploy-and-configure/configuration/dataintegration/index.md @@ -862,7 +862,7 @@ There exist a number of option for secure JDBC connections via Thrift and Hive: - User impersonation - Server and Client Certificates -Eccenca provides a custom Authentification provider which allows to set 1 user/password combination for JDBC connections via: +eccenca provides a custom Authentification provider which allows to set 1 user/password combination for JDBC connections via: ```code spark.sql.options = { diff --git a/docs/deploy-and-configure/configuration/explore/dataplatform/application-full.md b/docs/deploy-and-configure/configuration/explore/dataplatform/application-full.md index e2e7ce1a4..5d3afa1ec 100644 --- a/docs/deploy-and-configure/configuration/explore/dataplatform/application-full.md +++ b/docs/deploy-and-configure/configuration/explore/dataplatform/application-full.md @@ -5,6 +5,7 @@ tags: ## Deployment options for explore container + ***Property: deploy.apiPrefix*** diff --git a/docs/deploy-and-configure/configuration/explore/dataplatform/application-graphdb-full.md b/docs/deploy-and-configure/configuration/explore/dataplatform/application-graphdb-full.md index fc01381a6..c16507345 100644 --- a/docs/deploy-and-configure/configuration/explore/dataplatform/application-graphdb-full.md +++ b/docs/deploy-and-configure/configuration/explore/dataplatform/application-graphdb-full.md @@ -5,6 +5,8 @@ tags: ## Configuration for connecting to GraphDB backend + + Configuration example: This example configures a connection with HTTPS to a remote graphdb store () using the workbench import directory diff --git a/docs/deploy-and-configure/configuration/explore/dataplatform/application-http-full.md b/docs/deploy-and-configure/configuration/explore/dataplatform/application-http-full.md index d0ffacc3c..0ff438062 100644 --- a/docs/deploy-and-configure/configuration/explore/dataplatform/application-http-full.md +++ b/docs/deploy-and-configure/configuration/explore/dataplatform/application-http-full.md @@ -6,6 +6,8 @@ tags: ## Configuration for connecting to arbitrary SPARQL HTTP backend + + Use the following set of properties to connect to arbitrary HTTP SPARQL services. Configuration example: diff --git a/docs/deploy-and-configure/configuration/explore/dataplatform/application-inmemory-full.md b/docs/deploy-and-configure/configuration/explore/dataplatform/application-inmemory-full.md index 5918ea3fe..f852928ae 100644 --- a/docs/deploy-and-configure/configuration/explore/dataplatform/application-inmemory-full.md +++ b/docs/deploy-and-configure/configuration/explore/dataplatform/application-inmemory-full.md @@ -5,6 +5,8 @@ tags: ## Configuration for connecting to internal memory backend + + You can configure a in-memory SPARQL backend. Based on Jena Models, in-memory backends do not provide persistent storage. Hence, shutting down a DataPlatform configured with an in-memory backend deletes your data and therefore you should use it only for testing purposes. diff --git a/docs/deploy-and-configure/configuration/explore/dataplatform/application-oauth-full.md b/docs/deploy-and-configure/configuration/explore/dataplatform/application-oauth-full.md index 59d069441..4372397eb 100644 --- a/docs/deploy-and-configure/configuration/explore/dataplatform/application-oauth-full.md +++ b/docs/deploy-and-configure/configuration/explore/dataplatform/application-oauth-full.md @@ -6,6 +6,8 @@ tags: ### Authentication + + Access to DataPlatform resources is restricted using OAuth 2.0. #### Configuration example diff --git a/docs/deploy-and-configure/configuration/explore/dataplatform/application-virtuoso-full.md b/docs/deploy-and-configure/configuration/explore/dataplatform/application-virtuoso-full.md index ac7ac0143..88ee06693 100644 --- a/docs/deploy-and-configure/configuration/explore/dataplatform/application-virtuoso-full.md +++ b/docs/deploy-and-configure/configuration/explore/dataplatform/application-virtuoso-full.md @@ -5,6 +5,8 @@ tags: ## Configuration for connecting to Virtuoso backend + + Configuration example: This example configures a connection with HTTPS to a remote Virtuoso store (). diff --git a/docs/deploy-and-configure/configuration/graphinsights/index.md b/docs/deploy-and-configure/configuration/graphinsights/index.md index 8a4af03d7..c1b6bbd95 100644 --- a/docs/deploy-and-configure/configuration/graphinsights/index.md +++ b/docs/deploy-and-configure/configuration/graphinsights/index.md @@ -64,12 +64,12 @@ You should enable this in your `values.yaml` file. Also make sure you have set the clients and client credentials. See [Configure OAuth clients (helm)](#configure-oauth-clients-helm) -The configuration mentioned below is rendered with those files, but you usually don't have to touch those: +The configuration mentioned below is rendered with those files, but you usually do not have to touch those: - `configuration-files/explore-application.yml` for Explore - `configuration-files/cmem.integration.config.yml` for Graph Insights -For more details please have a look in the helm value file. +For more details have a look in the helm value file. Every configuration is documented there. Please refer to [Kubernetes deployments](../../../deploy-and-configure/installation/scenario-k8s-deployment/index.md) for more information. @@ -284,7 +284,7 @@ In case you want to have separate clients for production deployments, this chapt #### Configure OAuth clients (docker-compose) -In our **docker-orchestration** to enrol those other clients, please follow these steps: +In our **docker-orchestration** to enrol those other clients, follow these steps: 1.) take a look at `environments/default.env` and copy these variables to your `environments/config.env` file: diff --git a/docs/deploy-and-configure/configuration/keycloak/index.md b/docs/deploy-and-configure/configuration/keycloak/index.md index 090d7c28e..28d5c6050 100644 --- a/docs/deploy-and-configure/configuration/keycloak/index.md +++ b/docs/deploy-and-configure/configuration/keycloak/index.md @@ -46,7 +46,7 @@ There are two different types of clients used by Corporate Memory: - Similar to the `cmem` client you can configure Graph Insights to use a separate client (usually named `graph-insights`) - Similar to the `cmem-service-account` client you can configure Graph Insights to communicate with a separate client (usually named `graph-insights-service-account`) -For Graph Insight please refer the [Graph Insights OAUTH documentation](../../../deploy-and-configure/configuration/graphinsights/index.md#oauth-configuration) +For Graph Insight refer to the [Graph Insights OAUTH documentation](../../../deploy-and-configure/configuration/graphinsights/index.md#oauth-configuration) Depending on the environment, there might be other use cases, when running background schedules, then a third client, also as technical user, might be useful. ### Access conditions, roles and groups diff --git a/docs/deploy-and-configure/installation/migrating-stores/index.md b/docs/deploy-and-configure/installation/migrating-stores/index.md index a3930cf26..2953c1162 100644 --- a/docs/deploy-and-configure/installation/migrating-stores/index.md +++ b/docs/deploy-and-configure/installation/migrating-stores/index.md @@ -36,7 +36,7 @@ icon: material/database - optimizing customization (e.g. queries in SHAPES; DI; DM-config) - "textmatch" / "lucene" queries need to be migrated (a query can be helpful to find these queries...) - performance comparisons could be automated via `cmemc query replay` - - identify query that won't run or run slow + - identify query that will not run or run slow - general query best practices - → query optimization guide - use `VALUE` instead of `FILTER (?x IN (...))` (esp. on GDB) diff --git a/docs/deploy-and-configure/installation/scenario-local-installation/index.md b/docs/deploy-and-configure/installation/scenario-local-installation/index.md index e8e8cbf78..f625d1c81 100644 --- a/docs/deploy-and-configure/installation/scenario-local-installation/index.md +++ b/docs/deploy-and-configure/installation/scenario-local-installation/index.md @@ -17,7 +17,7 @@ The code examples in this section assume that you have a POSIX-compliant shell ( - [jq](https://jqlang.github.io/jq/download/) installed locally - Triple store license (provided by eccenca) - Graph Insights license (optional, provided by eccenca) -- make - build tool (apt-get install make) installed locally (don't use version 4.4.1 [→](https://savannah.gnu.org/bugs/?63650); e.g., 4.3 works well) +- make - build tool (apt-get install make) installed locally (do not use version 4.4.1 [→](https://savannah.gnu.org/bugs/?63650); e.g., 4.3 works well) - At least 4 CPUs and 12GB of RAM (recommended: 16GB) dedicated to docker ## Setup & Check Installation Environment diff --git a/docs/deploy-and-configure/requirements/index.md b/docs/deploy-and-configure/requirements/index.md index b90726e19..af9510eea 100644 --- a/docs/deploy-and-configure/requirements/index.md +++ b/docs/deploy-and-configure/requirements/index.md @@ -6,7 +6,7 @@ icon: material/exclamation-thick # Requirements This page lists software and hardware requirements for eccenca Corporate Memory deployments. -For a general overview of a deployment setup please refer to the [System Architecture](../system-architecture/index.md). +For a general overview of a deployment setup refer to the [System Architecture](../system-architecture/index.md). ## Minimal Setup diff --git a/docs/develop/cmemc-scripts/index.md b/docs/develop/cmemc-scripts/index.md index 034396a9a..5faedb02f 100644 --- a/docs/develop/cmemc-scripts/index.md +++ b/docs/develop/cmemc-scripts/index.md @@ -14,7 +14,7 @@ As a more lightweight and fault-tolerant alternative to using cmempy directly, w The advantages of this approach are: - You can test and use your calls in the command line before integrating them. -- You don't have to worry about internal details and have a well-documented and stable interface. +- You do not have to worry about internal details and have a well-documented and stable interface. - Authorization is done in the same way, cmemc is doing this. ## Installation diff --git a/docs/develop/python-plugins/setup/index.md b/docs/develop/python-plugins/setup/index.md index be77a32a9..de3eb9e43 100644 --- a/docs/develop/python-plugins/setup/index.md +++ b/docs/develop/python-plugins/setup/index.md @@ -123,7 +123,7 @@ The basic setup provides a `/data` directory inside of the Build (DataIntegratio The environment variable `PYTHONPATH` defines the directory, where the user-managed python packages are saved. This directory shall be persisted between restarts of Build (DataIntegration). The default value of this variable is `/data/python-packages/`. -DataIntegration won't start if the directory defined by `PYTHONPATH` is not present and can't be created. +DataIntegration will not start if the directory defined by `PYTHONPATH` is not present and cannot be created. In addition Build (DataIntegration) needs write access to that folder. This is tested on Build (DataIntegration) startup. diff --git a/docs/explore-and-author/companion/index.md b/docs/explore-and-author/companion/index.md index 7af251116..7d2d1bc1f 100644 --- a/docs/explore-and-author/companion/index.md +++ b/docs/explore-and-author/companion/index.md @@ -59,19 +59,19 @@ If your use case or question requires you to limit the available tools (e.g. if - Query Catalog related `query_list` - : Lists all existing SPARQL queries on this corporate memory instance. + : Lists all existing SPARQL queries on this Corporate Memory instance. `query_details` : Retrieve all information about a certain query in the query catalog. `query_execute_saved` - : Executes a saved SPARQL query on this corporate memory instance. + : Executes a saved SPARQL query on this Corporate Memory instance. The query is identified by its IRI. - Query related: `query_execute_json` - : Executes a `SPARQL SELECT` query on this corporate memory instance. + : Executes a `SPARQL SELECT` query on this Corporate Memory instance. The query is provided as a string. - Introspection related: @@ -83,7 +83,7 @@ If your use case or question requires you to limit the available tools (e.g. if : Shows how classes are connected in a particular graph to each other by different properties. `graph_list` - : Lists all existing RDF graphs on this corporate memory instance. + : Lists all existing RDF graphs on this Corporate Memory instance. `graph_properties_list` : Lists all used RDF properties used in this graph. diff --git a/docs/getting-started/with-your-sandbox/index.md b/docs/getting-started/with-your-sandbox/index.md index bd167cf63..f1c9bdb2e 100644 --- a/docs/getting-started/with-your-sandbox/index.md +++ b/docs/getting-started/with-your-sandbox/index.md @@ -11,7 +11,7 @@ hide: ![Your are here](overview-cmem.drawio.svg "You are here") -Thank you for registering your eccenca Corporate Memory Sandbox! We're excited to have you on board and look forward to showing you how Corporate Memory can help you with your data management needs. We hope that you find this experience valuable and informative. If you have any questions or feedback, please don't hesitate to reach out to us. Thanks again for joining us! +Thank you for registering your eccenca Corporate Memory Sandbox! We are excited to have you on board and look forward to showing you how Corporate Memory can help you with your data management needs. We hope that you find this experience valuable and informative. If you have any questions or feedback, do not hesitate to reach out to us. Thank you again for joining us! eccenca's Corporate Memory is a platform for creating and managing Enterprise Knowledge Graphs. It has three main stages: _Build_, _Explore_, and _Consume_. In the _Build_ stage, you can convert legacy data points from existing datasets into a Knowledge Graph structure. The _Explore_ stage allows you to interact with your Knowledge Graph, while the _Consume_ stage is used to retrieve information from the graph and integrate it programmatically with your IT infrastructure. diff --git a/docs/release-notes/corporate-memory-20-06/index.md b/docs/release-notes/corporate-memory-20-06/index.md index a6d70d577..184d7f96a 100644 --- a/docs/release-notes/corporate-memory-20-06/index.md +++ b/docs/release-notes/corporate-memory-20-06/index.md @@ -57,8 +57,8 @@ In addition to that, these changes are shipped: - RDF Workspace Provider: Improved reading of project data if Graph Store protocol is supported by RDF endpoint. - RDF Workspace Provider: Improved import of projects if Graph Store protocol is supported by RDF endpoint. - More consistent labels for tasks, operators and their parameters. -- If active learning is started with an existing linkage rule, it's also used to generate the unlabeled pool. -- `ExcelMapTransformer` reloads the referenced resource if it's modification time changed. For performance reasons the check may be deferred by some seconds. +- If active learning is started with an existing linkage rule, it is also used to generate the unlabeled pool. +- `ExcelMapTransformer` reloads the referenced resource if its modification time changed. For performance reasons the check may be deferred by some seconds. In addition to that, multiple performance and stability issues were solved. diff --git a/docs/release-notes/corporate-memory-20-12/index.md b/docs/release-notes/corporate-memory-20-12/index.md index e46935de7..830f4f799 100644 --- a/docs/release-notes/corporate-memory-20-12/index.md +++ b/docs/release-notes/corporate-memory-20-12/index.md @@ -164,4 +164,4 @@ js.config.workspaces: ### cmemc -- The `config check` command has been deprecated, please use the `admin status` command instead. +- The `config check` command has been deprecated, use the `admin status` command instead. diff --git a/docs/release-notes/corporate-memory-21-02/index.md b/docs/release-notes/corporate-memory-21-02/index.md index 23f2f19a6..a67b36645 100644 --- a/docs/release-notes/corporate-memory-21-02/index.md +++ b/docs/release-notes/corporate-memory-21-02/index.md @@ -177,7 +177,7 @@ In addition to that, these changes are shipped: - Timestamp to date operator changed default behavior - The "Timestamp to date" now assumes milliseconds instead of seconds by default. In addition, it generates full xsd:dateTime values instead of simple dates. - - To makes sure that existing usages don't break, please open {DataIntegration}/api/core/usages/plugins/timeToDate and check all usages. + - To makes sure that existing usages do not break, open {DataIntegration}/api/core/usages/plugins/timeToDate and check all usages. - In order to revert to the previous behavior, the following changes have to be made to each usage: - Change the unit to "seconds". - Change the format to "yyyy-MM-dd" diff --git a/docs/release-notes/corporate-memory-21-04/index.md b/docs/release-notes/corporate-memory-21-04/index.md index 64db2437f..bc7003374 100644 --- a/docs/release-notes/corporate-memory-21-04/index.md +++ b/docs/release-notes/corporate-memory-21-04/index.md @@ -106,9 +106,9 @@ In addition to that, these changes are shipped: - Use redux store to manage notifications in DataManager (MessageHandler) and improve error parse / handle - Use redux store to manage main application state. - Change value of `js.config.modules.explore.overallSearchQuery` and `js.config.modules.explore.navigation.searchQuery` to use the `""""` SPARQL string separator. - - *BREAK* please use `"""` if you use custom queries for that values + - *BREAK* use `"""` if you use custom queries for that values - Development - - Switch to GUI elements repository from Github + - Switch to GUI elements repository from GitHub In addition to that, multiple performance and stability issues were solved. diff --git a/docs/release-notes/corporate-memory-21-11/index.md b/docs/release-notes/corporate-memory-21-11/index.md index 9e314fd42..c89c9ea85 100644 --- a/docs/release-notes/corporate-memory-21-11/index.md +++ b/docs/release-notes/corporate-memory-21-11/index.md @@ -78,7 +78,7 @@ In addition to that, these changes are shipped: - Mapping Rule Editor will show the rule label (if any) and the mapping target. - The JSON dataset supports streaming. - The change applies to reading JSON, writing was already streamed. - - If streaming is enabled, files won't be loaded into memory, allowing to read large JSON files without running into OutOfMemory errors. + - If streaming is enabled, files will not be loaded into memory, allowing to read large JSON files without running into OutOfMemory errors. - Allow to open the value mapping rule formula editor from the create/edit value mapping rule form. - Improvements to Template operators: - Added option to forward input attributes. @@ -107,7 +107,7 @@ This version of eccenca DataManager adds the following new features: - can get expanded permanently - offers option to get expanded in a reduced form by hovering it with the cursor - we now have various section in the main nav, modules with main navigation items can be configured via `subSection` parameter (order of sections need to be defined in `Navigationbar` component, currently we have `timetracker`, `explore`, `build` and `other` as options, if not set it is automatically organized into `explore` or `other`) - - **Deprecation notice:** configuration variables `windowTitle` and `headerName` are now deprecated, please use `companyName`, `productName` and `applicationName` from `appPresentation` + - **Deprecation notice:** configuration variables `windowTitle` and `headerName` are now deprecated, use `companyName`, `productName` and `applicationName` from `appPresentation` - Query Module - New Query Module v2 - Activated per default @@ -197,7 +197,7 @@ This version of eccenca DataPlatform ships the following new features: - Prefixes are now used in TURTLE serializations - Prefixes defined in the Vocaulary catalog are used. - Added support for all shacl:path expressions - - `shui:inversePath` is still supported, however please use [`sh:inversePath`](https://www.w3.org/TR/shacl/#property-path-inverse) wherever possible. + - `shui:inversePath` is still supported, however, use [`sh:inversePath`](https://www.w3.org/TR/shacl/#property-path-inverse) wherever possible. - Property usage analytics endpoints `api/vocabusage/*` for both explicit Vocab definitions and usage information. Please refer to the OpenAPI definitions for more information. - Explicitly defined supported-submit-methods property to enable / disable "Try I Out" button in Swagger UI. - Server side UI configuration Support diff --git a/docs/release-notes/corporate-memory-22-1/index.md b/docs/release-notes/corporate-memory-22-1/index.md index 003a10ae6..3e5ac254e 100644 --- a/docs/release-notes/corporate-memory-22-1/index.md +++ b/docs/release-notes/corporate-memory-22-1/index.md @@ -217,7 +217,7 @@ In addition to that, multiple performance and stability issues were solved. ### DataPlatform -- While updating, property `spring.profiles=PROFILE` needs to be replaced by `spring.config.activate.on-profile`. For further information, please see [this blog post](https://spring.io/blog/2020/08/14/config-file-processing-in-spring-boot-2-4). +- While updating, property `spring.profiles=PROFILE` needs to be replaced by `spring.config.activate.on-profile`. For further information, see [this blog post](https://spring.io/blog/2020/08/14/config-file-processing-in-spring-boot-2-4). - Removed custom redirect for Swagger UI under `/swagger-ui`. Swagger UI only accessible under `/swagger-ui.html` (Spring Boot Default) ### cmemc diff --git a/docs/release-notes/corporate-memory-23-1/index.md b/docs/release-notes/corporate-memory-23-1/index.md index a8eaaee63..0ba2eef35 100644 --- a/docs/release-notes/corporate-memory-23-1/index.md +++ b/docs/release-notes/corporate-memory-23-1/index.md @@ -200,7 +200,7 @@ v23.1 of eccenca DataManager adds the following new features: v23.1 of eccenca DataManager introduces the following changes: -- Configuration is now fully retrieved from DataPlatform, the included Spring Boot based backend is solely delivering the javascript frontend. +- Configuration is now fully retrieved from DataPlatform, the included Spring Boot based backend is solely delivering the JavaScript frontend. - The configuration can be changed at runtime using a frontend in the `/admin` Module. Changes are visible with the next full browser reload. - Authentication is now based on the OAuth2 Code Flow. diff --git a/docs/release-notes/corporate-memory-23-3/index.md b/docs/release-notes/corporate-memory-23-3/index.md index edc852c75..68b35078c 100644 --- a/docs/release-notes/corporate-memory-23-3/index.md +++ b/docs/release-notes/corporate-memory-23-3/index.md @@ -118,7 +118,7 @@ v23.3.0 of DataManager ships the following changes: - Internal: - Query module is migrated from Redux to a Context storage. - Query module is extracted to a separate common component. -- ResourceSelect doesn't request options anymore if they have already been requested earlier. +- ResourceSelect does not request options anymore if they have already been requested earlier. - `shui:listQuery` allows usage of the `{{username}}` placeholder, which is replaced by the name (i.e.not the IRI) of the logged in user. v23.3.0 of DataManager ships the following fixes: diff --git a/docs/release-notes/corporate-memory-24-1/index.md b/docs/release-notes/corporate-memory-24-1/index.md index 99a37f5fa..8b9cc246e 100644 --- a/docs/release-notes/corporate-memory-24-1/index.md +++ b/docs/release-notes/corporate-memory-24-1/index.md @@ -61,7 +61,7 @@ v24.1.1 of DataIntegration adds the following new features: v24.1.1 of DataIntegration introduces the following changes: -- Icon of notification menu was aligned to DM, it's now a bell. +- Icon of notification menu was aligned to DM, it is now a bell. v24.1.1 of DataIntegration ships the following fixes: diff --git a/docs/release-notes/corporate-memory-24-2/index.md b/docs/release-notes/corporate-memory-24-2/index.md index 1e2026ae9..36391fac9 100644 --- a/docs/release-notes/corporate-memory-24-2/index.md +++ b/docs/release-notes/corporate-memory-24-2/index.md @@ -62,7 +62,7 @@ v24.2.0 of DataIntegration introduces the following changes: - Rule editors: Add generic path operator to input path tabs. - When trying to execute an unsaved workflow notify the user that the workflow will be saved with the option to not show the dialog again. - Re-added reload button to data preview to get updated content on config and data changes. -- Removed URL resource manager. URLs as file names won't be resolved anymore, e.g. for dataset inputs. +- Removed URL resource manager. URLs as file names will not be resolved anymore, e.g. for dataset inputs. - The RDF datasets will always write the schema type for each entity. v24.2.0 of DataIntegration ships the following fixes: diff --git a/docs/release-notes/corporate-memory-24-3/index.md b/docs/release-notes/corporate-memory-24-3/index.md index 8de9c28db..1832d3461 100644 --- a/docs/release-notes/corporate-memory-24-3/index.md +++ b/docs/release-notes/corporate-memory-24-3/index.md @@ -107,7 +107,7 @@ We're excited to bring you the latest update to DataIntegration v24.3, which int - Optimized writing to Neo4j, resulting in a 25x speed improvement. - Upgraded Spark to 3.5.3. -- Upgraded to typescript version 5.5.3. +- Upgraded to TypeScript version 5.5.3. - After saving a workflow the undo/redo queues are cleared which is consistent with other editors in DI/DM. - Renamed DI action from `urn:eccenca:di` to ``. - Line breaks are forced for evaluation preview tooltips. diff --git a/tests/test_rumdl_md044_allowlist.py b/tests/test_rumdl_md044_allowlist.py new file mode 100644 index 000000000..aca1b15f9 --- /dev/null +++ b/tests/test_rumdl_md044_allowlist.py @@ -0,0 +1,150 @@ +"""Test the MD044 allowlist for technical identifiers in .rumdl.toml + +MD044 enforces the capitalization of proper names such as ``GitHub`` or ``eccenca``. +Some technical identifiers in the documentation contain those names but must keep +their exact spelling: Material icon shortcodes, hostnames and environment variables. + +They are protected by listing the longer identifier in ``[MD044].names`` *before* the +brand name, so the longer match wins. These tests pin that behaviour down - both that +the identifiers survive ``rumdl --fix`` and that the rule still catches real prose. +""" +import json +import pathlib +import shutil +import subprocess +import tomllib + +import pytest + +REPO_ROOT = pathlib.Path(__file__).resolve().parents[1] +RUMDL_CONFIG = REPO_ROOT / ".rumdl.toml" + +# Technical identifiers that contain a proper name but must never be rewritten. +# Each entry is a snippet taken from the documentation as it is written today. +PROTECTED_SNIPPETS = { + "frontmatter-icon-github": '---\ntitle: "cmemc: Using GitHub Actions"\nicon: material/github\n---\n', + "frontmatter-icon-gitlab": '---\ntitle: "cmemc: Using GitLab Pipelines"\nicon: material/gitlab\n---\n', + "material-icon-github": "- :material-github: [GitHub Actions](github-action/index.md)\n", + "material-icon-gitlab": "- :material-gitlab: [GitLab Pipelines](gitlab-pipeline/index.md)\n", + "simple-icon-github": "- :simple-github:{ .lg .middle } GitHub\n", + "simple-icon-gitlab": "- :simple-gitlab:{ .lg .middle } GitLab\n", + "hostname": '=== "Installation via gitlab.eccenca.com"\n', + "env-var": "| Environment | LOGGING_LEVEL_COM_ECCENCA_ELDS_BACKEND |\n", + "env-var-long": ( + "| Environment | LOGGING_LEVEL_COM_ECCENCA_ELDS_BACKEND_WEBAPP_WEB_FILTER_SIMPLECORSFILTER |\n" + ), +} + +# Misspellings in running text that MD044 must keep reporting, so that the +# allowlist above cannot silently switch the whole rule off. +PROSE_VIOLATIONS = [ + ("The Github project provides an example.", "Github", "GitHub"), + ("You can use cmemc in Gitlab pipelines.", "Gitlab", "GitLab"), + ("The backend delivers the javascript frontend.", "javascript", "JavaScript"), + ("Upgraded to typescript version 5.5.3.", "typescript", "TypeScript"), + ("Eccenca provides a custom authentication provider.", "Eccenca", "eccenca"), + ("Lists all RDF graphs on this corporate memory instance.", "corporate memory", "Corporate Memory"), +] + +pytestmark = pytest.mark.skipif( + shutil.which("rumdl") is None, reason="rumdl is not installed in this environment" +) + + +def _rumdl(path, *extra_args): + """Run rumdl for MD044 only against path and return the completed process.""" + result = subprocess.run( + [ + "rumdl", + "--config", + str(RUMDL_CONFIG), + "check", + "--enable", + "MD044", + *extra_args, + str(path), + ], + capture_output=True, + text=True, + check=False, + ) + # rumdl exits 1 when it reports findings, so only a crash is an error here + assert result.returncode in (0, 1), f"rumdl failed: {result.stderr}" + return result + + +def _findings(path): + """Return the MD044 findings for path as parsed JSON.""" + result = _rumdl(path, "--output-format", "json") + return json.loads(result.stdout or "[]") + + +def _fix(path): + """Apply the MD044 auto-fix to path in place. + + Deliberately without ``--output-format json``: combining that with ``--fix`` + makes rumdl report the fixes but leave the file untouched, which would turn + every assertion below into a no-op. + """ + _rumdl(path, "--fix") + + +def _write(tmp_path, name, content): + """Write a markdown fixture and return its path.""" + target = tmp_path / f"{name}.md" + target.write_text(content, encoding="utf-8") + return target + + +@pytest.mark.parametrize("name, snippet", sorted(PROTECTED_SNIPPETS.items())) +def test_md044_does_not_report_technical_identifiers(tmp_path, name, snippet): + """Icon shortcodes, hostnames and environment variables are not MD044 findings.""" + findings = _findings(_write(tmp_path, name, snippet)) + assert findings == [], f"{name} should be covered by the MD044 allowlist" + + +@pytest.mark.parametrize("name, snippet", sorted(PROTECTED_SNIPPETS.items())) +def test_md044_fix_leaves_technical_identifiers_untouched(tmp_path, name, snippet): + """`rumdl --fix` must not rewrite the protected identifiers. + + This is the regression that matters: a missing allowlist entry does not just add + noise, it makes the auto-fix break icons, hostnames and environment variables. + """ + target = _write(tmp_path, name, snippet) + _fix(target) + assert target.read_text(encoding="utf-8") == snippet + + +@pytest.mark.parametrize("text, wrong, correct", PROSE_VIOLATIONS) +def test_md044_still_reports_proper_names_in_prose(tmp_path, text, wrong, correct): + """The allowlist must not weaken MD044 for ordinary running text.""" + findings = _findings(_write(tmp_path, "prose", f"{text}\n")) + messages = [finding["message"] for finding in findings] + assert messages == [f"Proper name '{wrong}' should be '{correct}'"] + + +def test_md044_fix_corrects_prose(tmp_path): + """`rumdl --fix` still repairs the proper names it is meant to repair.""" + target = _write(tmp_path, "prose", "The Github project uses javascript.\n") + _fix(target) + assert target.read_text(encoding="utf-8") == "The GitHub project uses JavaScript.\n" + + +def test_md044_allowlist_orders_identifiers_before_brand_names(): + """The technical identifiers must stay listed before the brand names they contain. + + MD044 resolves overlapping names by the longer match, but keeping the order also + keeps the intent readable for whoever edits the list next. + """ + names = tomllib.loads(RUMDL_CONFIG.read_text(encoding="utf-8"))["MD044"]["names"] + for identifier, brand in ( + ("material/github", "GitHub"), + ("material-gitlab", "GitLab"), + ("simple-github", "GitHub"), + ("gitlab.eccenca.com", "eccenca"), + ("COM_ECCENCA", "eccenca"), + ): + assert identifier in names, f"{identifier} is missing from [MD044].names" + assert names.index(identifier) < names.index(brand), ( + f"{identifier} must be listed before {brand}" + )