fix: documentation links and update references (#551)

Author: AlexanderLanin

docs/how-to/other_modules.rst

@@ -48,7 +48,7 @@ Example `BUILD` snippet (consumer module):
 
 .. code-block:: starlark
 
-    load("@rules_docs//:docs.bzl", "docs")
+    load("@score_docs_as_code//:docs.bzl", "docs")
     docs(
       data = [
          "@score_process//:needs_json",

docs/how-to/setup.md

@@ -23,7 +23,7 @@ designed to enhance documentation capabilities in S-CORE.
 Add the module to your `MODULE.bazel` file:
 
 ```starlark
-bazel_dep(name = "score_docs_as_code", version = "4.0.1")
+bazel_dep(name = "score_docs_as_code", version = "4.1.0")
 ```
 
 And make sure to also add the S-core Bazel registry to your `.bazelrc` file

docs/how-to/source_to_doc_links.rst

@@ -53,7 +53,7 @@ Finally, pass the scan results to the ``docs`` rule as ``scan_code`` attribute.
           "foo.py",
           "bar.cpp",
           "data.yaml",
-      ] + glob(["subdir/**/.py"]),
+      ] + glob(["subdir/**/*.py"]),
    )
 
    docs(

docs/internals/extensions/extension_guide.md

@@ -6,7 +6,7 @@ This document will help you with the most important building blocks and provide
 
 ## Getting Started
 
-1. Create a new folder in `docs/_tooling/extensions` called `score_<name of your extension>`
+1. Create a new folder in `src/extensions` called `score_<name of your extension>`
 2. Copy the template inside the `__init__.py`
 3. Adapt to your needs
 
@@ -76,7 +76,7 @@ extensions = [
 ]
 ```
 
-> **Important:** There cannot be any BUILD file inside the entire 'extensions' folder, as that would break the Python imports.
+> **Important:** Each extension needs its own `BUILD` file to declare the `py_library` target and its dependencies.
 
 
 
@@ -90,16 +90,13 @@ We perform testing with unit tests as well as integration tests that validate th
 ### Where to Place Your Test Code
 
 ```bash
-_tooling/
-├── extensions/
-│   ├── README.md
-│   ├── score_draw_uml_funcs/
-│   ├── YOUR_EXTENSION/
-│   │   ├── __init__.py  # your python code (setup needs to be in here)
-│   │   ├── xyz.py       # your python code (if you need/want to split it across different files)
-│   │   └── tests/
-│   │       ├── test_xyz.py             # unit tests
-│   │       └── test_YOUR_EXTENSION.py  # integration tests
+src/extensions/
+├── YOUR_EXTENSION/
+│   ├── __init__.py  # your python code (setup needs to be in here)
+│   ├── xyz.py       # your python code (if you need/want to split it across different files)
+│   └── tests/
+│       ├── test_xyz.py             # unit tests
+│       └── test_YOUR_EXTENSION.py  # integration tests
 ├── score_metamodel/
 ├── score_plantuml.py
 ```

docs/internals/extensions/index.rst

@@ -19,8 +19,6 @@
 Extensions
 ==========
 
-Hello there
-
 
 .. grid:: 1 1 3 3
    :class-container: score-grid

docs/internals/extensions/source_code_linker.md

@@ -371,14 +371,6 @@ score_source_code_linker/
 
 ---
 
-## Clearing Cache Manually
-
-To clear the build cache, run:
-
-```bash
-rm -rf _build/
-```
-
 ## Examples
 
 To see working examples for CodeLinks & TestLinks, take a look at the Docs-As-Code documentation.

docs/internals/requirements/tool_req_overview.rst

@@ -58,12 +58,17 @@ It should be treated as a 'get-started' guide, giving you all needed information
 
 ```
 src/
-├── assets/           # Documentation styling (CSS)
-├── decision_records/ # Architecture Decision Records (ADRs)
 ├── extensions/       # Custom Sphinx extensions
-│   └── score_metamodel/
-│       ├── checks/   # Sphinx-needs validation
-│       └── tests/    # Extension test suite
+│   ├── score_metamodel/
+│   │   ├── checks/   # Sphinx-needs validation
+│   │   └── tests/    # Extension test suite
+│   ├── score_source_code_linker/
+│   ├── score_sphinx_bundle/
+│   ├── score_layout/
+│   ├── score_draw_uml_funcs/
+│   ├── score_plantuml.py
+│   └── score_sync_toml/
+├── helper_lib/       # Shared utilities
 └── templates/        # HTML templates
 ```
 
@@ -78,7 +83,7 @@ Find everything related to testing and how to add your own test suite [here](/sr
 2. Create a dedicated test directory
 3. Include an appropriate README in markdown
 
-> If you want to develop your own Sphinx extension, check out the [extensions guide](/src/extensions/README.md)
+> If you want to develop your own Sphinx extension, check out the [extensions guide](/docs/internals/extensions/extension_guide.md)
 
 ## Updating dependencies
 
@@ -101,7 +106,7 @@ bazel run //src:requirements.update -- --upgrade
 
 1. **Documentation**
    - Keep READMEs up-to-date
-   - Document architectural decisions in `decision_records/`
+   - Document architectural decisions in `docs/internals/decisions/`
    - Include examples in extension documentation
 
 2. **Testing**
@@ -129,6 +134,6 @@ Common issues and solutions:
    - Verify extension dependencies
 
 ## Additional Resources
-- [Sphinx extension guide](/src/extensions/README.md)
-- [S-CORE Metamodel Documentation](/src/extensions/score_metamodel/README.md)
-- [Pytest Integration Guide](/tools/testing/pytest/README.md)
+- [Sphinx extension guide](/docs/internals/extensions/extension_guide.md)
+- [S-CORE Metamodel Documentation](/docs/internals/extensions/metamodel.md)
+- [Pytest Integration Guide](/score_pytest/README.md)