diff --git a/docs/how-to/other_modules.rst b/docs/how-to/other_modules.rst index c1a2e18c0..a64c65568 100644 --- a/docs/how-to/other_modules.rst +++ b/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", diff --git a/docs/how-to/setup.md b/docs/how-to/setup.md index 9005a6bef..bd210250a 100644 --- a/docs/how-to/setup.md +++ b/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 diff --git a/docs/how-to/source_to_doc_links.rst b/docs/how-to/source_to_doc_links.rst index cbb6d8801..29341762f 100644 --- a/docs/how-to/source_to_doc_links.rst +++ b/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( diff --git a/docs/internals/extensions/extension_guide.md b/docs/internals/extensions/extension_guide.md index 74e14c2f8..77da432f1 100644 --- a/docs/internals/extensions/extension_guide.md +++ b/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_` +1. Create a new folder in `src/extensions` called `score_` 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 ``` diff --git a/docs/internals/extensions/index.rst b/docs/internals/extensions/index.rst index 194370bfb..cfe2f7c44 100644 --- a/docs/internals/extensions/index.rst +++ b/docs/internals/extensions/index.rst @@ -19,8 +19,6 @@ Extensions ========== -Hello there - .. grid:: 1 1 3 3 :class-container: score-grid diff --git a/docs/internals/extensions/source_code_linker.md b/docs/internals/extensions/source_code_linker.md index c9b849e8f..4b3aed154 100644 --- a/docs/internals/extensions/source_code_linker.md +++ b/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. diff --git a/docs/internals/requirements/tool_req_overview.rst b/docs/internals/requirements/tool_req_overview.rst deleted file mode 100644 index 2ae20c6bb..000000000 --- a/docs/internals/requirements/tool_req_overview.rst +++ /dev/null @@ -1,28 +0,0 @@ -.. - # ******************************************************************************* - # Copyright (c) 2026 Contributors to the Eclipse Foundation - # - # See the NOTICE file(s) distributed with this work for additional - # information regarding copyright ownership. - # - # This program and the accompanying materials are made available under the - # terms of the Apache License Version 2.0 which is available at - # https://www.apache.org/licenses/LICENSE-2.0 - # - # SPDX-License-Identifier: Apache-2.0 - # ******************************************************************************* - -.. _docs_tool_req_overview: - -:orphan: - -Tool Requirements Overview (Deprecated) -======================================= - -This page is deprecated. - -Use the canonical requirements dashboard: -:doc:`implementation_state` - -The process-to-tool mapping tables previously shown here are now part of -the implementation state dashboard. diff --git a/src/README.md b/src/README.md index 61e08db94..f0c601869 100644 --- a/src/README.md +++ b/src/README.md @@ -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)