### Install Development Dependencies with Tox

Source: https://github.com/useblocks/sphinx-codelinks/blob/main/docs/source/development/contributing.rst

Install tox and tox-uv to manage development tasks. Use pip or uv for installation.

```bash
pip install tox tox-uv
```

```bash
uv tool install tox --with tox-uv
```

--------------------------------

### Complete Sphinx-CodeLinks Configuration Example

Source: https://github.com/useblocks/sphinx-codelinks/blob/main/docs/source/components/configuration.rst

A comprehensive TOML configuration example for Sphinx-CodeLinks, demonstrating settings for source discovery, analysis, and comment styling.

```toml
[codelinks]
outdir = "output"

[codelinks.projects.my_project.source_discover]
src_dir = "./"
exclude = []
include = []
gitignore = true
follow_links = false
comment_type = "cpp"

[codelinks.projects.my_project.analyse]
get_need_id_refs = true
get_oneline_needs = true
get_rst = true
# Optional: Explicit Git root for Bazel or deeply nested configs
# git_root = "/path/to/repo"

[codelinks.projects.my_project.analyse.oneline_comment_style]
start_sequence = "@"
# End sequences is newline by default. Whether it is "\n" or "\r\n" depending on the platform
end_sequence = "\n"
field_split_char = ","
needs_fields = [
    { name = "title", type = "str" },
    { name = "id", type = "str" },
    { name = "type", type = "str", default = "impl" },
    { name = "links", type = "list[str]", default = [] },
]

[codelinks.projects.my_project.analyse.need_id_refs]
markers = ["@need-ids:"]

[codelinks.projects.my_project.analyse.marked_rst]
start_sequence = "@rst"
end_sequence = "@endrst"
```

--------------------------------

### Example src_trace.toml Configuration

Source: https://github.com/useblocks/sphinx-codelinks/blob/main/docs/source/components/directive.rst

This TOML file defines the configuration for source tracing, including project names and paths.

```toml
[project.dcdc]
path = "./tests/data/dcdc"

```

--------------------------------

### Install Pre-commit Hooks

Source: https://github.com/useblocks/sphinx-codelinks/blob/main/docs/source/development/contributing.rst

Install pre-commit to automatically run formatting and linting checks on every commit. Can also be run manually on all files.

```bash
pre-commit install
```

```bash
pre-commit run --all-files
```

--------------------------------

### Install sphinx-codelinks using Pip

Source: https://github.com/useblocks/sphinx-codelinks/blob/main/docs/source/basics/installation.rst

Use this command to install the sphinx-codelinks package via pip.

```bash
pip install sphinx-codelinks
```

--------------------------------

### Docstring Example with Type Annotations

Source: https://github.com/useblocks/sphinx-codelinks/blob/main/AGENTS.md

Illustrates a Python function with comprehensive type annotations and a Sphinx-style docstring. This follows best practices for code clarity and maintainability.

```python
def discover_source_files(
    root_dir: Path,
    include_patterns: list[str],
    exclude_patterns: list[str],
    *,
    respect_gitignore: bool = True,
) -> list[Path]:
    """Discover source files matching the given patterns.

    :param root_dir: The root directory to search from.
    :param include_patterns: Glob patterns for files to include.
    :param exclude_patterns: Glob patterns for files to exclude.
    :param respect_gitignore: Whether to respect .gitignore rules.
    :return: List of discovered file paths.
    :raises ValueError: If root_dir does not exist.
    """
    ...
```

--------------------------------

### Example C++ File Analysis Test

Source: https://github.com/useblocks/sphinx-codelinks/blob/main/AGENTS.md

Demonstrates a typical test structure for analyzing a C++ file using pytest and syrupy for snapshot assertions. Ensure 'analyse_file' is defined and accessible.

```python
import pytest
from pathlib import Path

def test_analyse_cpp_file(snapshot, tmp_path):
    """Test C++ file analysis produces correct output."""
    # Arrange
    source_file = tmp_path / "test.cpp"
    source_file.write_text("""
    // @req{REQ-001}
    void function() {}
    """)

    # Act
    result = analyse_file(source_file)

    # Assert
    assert snapshot == result

```

--------------------------------

### Architecture Pipeline Overview

Source: https://github.com/useblocks/sphinx-codelinks/blob/main/AGENTS.md

The code analysis follows a multi-stage pipeline, starting from source files and ending with RST generation. Each stage performs a specific task in the analysis process.

```text
Source Files → Discovery → Parsing → Analysis → Results (JSON) → RST Generation
```

--------------------------------

### Extract Sphinx-Needs ID References (C++)

Source: https://github.com/useblocks/sphinx-codelinks/blob/main/docs/source/components/analyse.rst

Example of C++ code with '@need-ids' markers and the resulting JSON output. Ensure the analyse configuration supports C++ comment styles.

```cpp
#include <iostream>

// @need-ids: need_001, need_002, need_003, need_004
void dummy_func1(){
    //...
}

// @need-ids: need_003
int main() {
    std::cout << "Starting demo_1..." << std::endl;
    dummy_func1();
    std::cout << "Demo_1 finished." << std::endl;
    return 0;
}
```

```json
[
    {
        "filepath": "tests/data/need_id_refs/dummy_1.cpp",
        "remote_url": "https://github.com/useblocks/sphinx-codelinks/blob/fa5a9129d60203355ae9fe4a725246a88522c60c/tests/data/need_id_refs/dummy_1.cpp#L3",
        "source_map": {
            "start": { "row": 2, "column": 13 },
            "end": { "row": 2, "column": 51 }
        },
        "tagged_scope": "void dummy_func1(){\n     //...\n }",
        "need_ids": ["need_001", "need_002", "need_003", "need_004"],
        "marker": "@need-ids:",
        "type": "need-id-refs"
    },
    {
        "filepath": "tests/data/need_id_refs/dummy_1.cpp",
        "remote_url": "https://github.com/useblocks/sphinx-codelinks/blob/fa5a9129d60203355ae9fe4a725246a88522c60c/tests/data/need_id_refs/dummy_1.cpp#L8",
        "source_map": {
            "start": { "row": 7, "column": 13 },
            "end": { "row": 7, "column": 21 }
        },
        "tagged_scope": "int main() {\n   std::cout << \"Starting demo_1...\" << std::endl;\n   dummy_func1();\n   std::cout << \"Demo_1 finished.\" << std::endl;\n   return 0;\n }",
        "need_ids": ["need_003"],
        "marker": "@need-ids:",
        "type": "need-id-refs"
    }
]
```

--------------------------------

### Equivalent RST for One-line Need

Source: https://github.com/useblocks/sphinx-codelinks/blob/main/docs/source/components/analyse.rst

This RST block shows the equivalent directive for the one-line comment example. It demonstrates how the simplified comment syntax translates into standard Sphinx-Needs RST.

```rst
.. impl:: Function Implementation
    :id: IMPL_001
    :links: REQ_001, REQ_002

```

--------------------------------

### Add New CLI Command

Source: https://github.com/useblocks/sphinx-codelinks/blob/main/AGENTS.md

Example of adding a new command to the CLI using Typer decorators. This involves defining the command function with arguments and a help description.

```python
@app.command()
def new_command(arg: str = typer.Argument(..., help="Description")):
    """Command description."""
    # Implementation
```

--------------------------------

### Add Java Analyzer

Source: https://github.com/useblocks/sphinx-codelinks/blob/main/AGENTS.md

Example of how to create a language-specific analyzer for Java by extending BaseAnalyzer. This involves defining the language, parser language, and the method to extract comment nodes from a parsed tree.

```python
class JavaAnalyzer(BaseAnalyzer):
    language = "java"
    parser_language = "java"

    def get_comment_nodes(self, tree):
        # Return comment nodes from tree
```

--------------------------------

### One-line comment with positional fields

Source: https://github.com/useblocks/sphinx-codelinks/blob/main/docs/source/components/oneline.rst

Illustrates a one-line comment where fields are defined positionally according to the 'needs_fields' configuration. This example shows the title, ID, type, and links in their specified order.

```c
// @ this is title, this is id, this_type, [link1, link2]
```

--------------------------------

### Configure Marked RST Block Extraction

Source: https://github.com/useblocks/sphinx-codelinks/blob/main/docs/source/components/configuration.rst

Define start and end sequences for extracting blocks of RST content embedded within source code comments. This is useful for including documentation directly in code.

```toml
[codelinks.projects.my_project.analyse.marked_rst]
start_sequence = "@rst"
end_sequence = "@endrst"

```

--------------------------------

### One-line comment for needs with links

Source: https://github.com/useblocks/sphinx-codelinks/blob/main/docs/source/components/oneline.rst

Example of a one-line comment defining a need with a title, ID, type, and a list of links. The 'links' field uses comma separation within brackets as per the 'list[str]' type.

```c
// @ title, id_123, implementation, [link1, link2]
```

--------------------------------

### Live Documentation Build with Auto-Reload

Source: https://github.com/useblocks/sphinx-codelinks/blob/main/AGENTS.md

Build documentation and serve it with live auto-reloading in the browser. This is ideal for development.

```bash
tox -e docs-live
```

--------------------------------

### Build Documentation with Tox

Source: https://github.com/useblocks/sphinx-codelinks/blob/main/docs/source/development/contributing.rst

Build the project documentation using the tox 'docs-clean' environment.

```bash
tox -e docs-clean
```

--------------------------------

### Run Needextend Demo

Source: https://github.com/useblocks/sphinx-codelinks/blob/main/tests/data/needextend_demo/README.md

Execute this command in the project root to generate the demo.

```bash
tox -e demo

```

--------------------------------

### Use src-trace Directive with Directory Option (Demo Project)

Source: https://github.com/useblocks/sphinx-codelinks/blob/main/docs/source/components/directive.rst

Trace needs from all files within the './discharge' directory of the 'dcdc' demo project. The directive will search recursively.

```rst
.. src-trace::
   :project: dcdc
   :directory: ./discharge
```

--------------------------------

### Use src-trace Directive with File Option (Demo Project)

Source: https://github.com/useblocks/sphinx-codelinks/blob/main/docs/source/components/directive.rst

Trace needs from a specific file within the 'dcdc' demo project. The path is relative to the project's source directory.

```rst
.. src-trace::
   :project: dcdc
   :file: ./charge/demo_1.cpp
```

--------------------------------

### Build Documentation Incrementally with Tox

Source: https://github.com/useblocks/sphinx-codelinks/blob/main/AGENTS.md

Update the project documentation incrementally after a clean build. This is faster for subsequent builds.

```bash
tox -e docs-update
```

--------------------------------

### Basic Source Discover Configuration

Source: https://github.com/useblocks/sphinx-codelinks/blob/main/docs/source/components/discover.rst

Configure the source directory and comment type for basic source file discovery.

```toml
[source_discover]
src_dir = "./src"
comment_type = "cpp"
```

--------------------------------

### Display CLI Help

Source: https://github.com/useblocks/sphinx-codelinks/blob/main/docs/source/components/cli.rst

Access the help page for the Sphinx-CodeLinks CLI by appending -h or --help to the command. This displays available options and usage instructions.

```bash
codelinks -h
```

```bash
codelinks --help
```

--------------------------------

### Run Default Test Environment with Tox

Source: https://github.com/useblocks/sphinx-codelinks/blob/main/AGENTS.md

Execute the default test suite using tox. This command ensures all tests pass in a consistent environment.

```bash
tox
```

--------------------------------

### Enable Following Symbolic Links in Source Discovery

Source: https://github.com/useblocks/sphinx-codelinks/blob/main/docs/source/components/configuration.rst

Set `follow_links` to `true` to enable traversal of symbolic links to directories during file discovery. By default, these links are not followed.

```toml
[codelinks.projects.my_project.source_discover]
follow_links = true
```

--------------------------------

### Run Pre-commit Hooks

Source: https://github.com/useblocks/sphinx-codelinks/blob/main/AGENTS.md

Execute all configured pre-commit hooks on all files in the repository. This is typically used to ensure code style and quality before committing.

```bash
pre-commit run --all-files
```

--------------------------------

### Build Docs with Different Builder using Tox

Source: https://github.com/useblocks/sphinx-codelinks/blob/main/AGENTS.md

Build documentation using a specific Sphinx builder, such as 'linkcheck', by setting the BUILDER environment variable.

```bash
BUILDER=linkcheck tox -e docs-clean
```

--------------------------------

### Define Project Configurations

Source: https://github.com/useblocks/sphinx-codelinks/blob/main/docs/source/components/configuration.rst

Define configurations for individual source code projects within the 'projects' section. Each project is identified by a unique name.

```toml
[codelinks.projects.my_project]
# Configuration for "my_project"

[codelinks.projects.another_project]
# Configuration for "another_project"
```

--------------------------------

### Activate sphinx-codelinks in conf.py

Source: https://github.com/useblocks/sphinx-codelinks/blob/main/docs/source/basics/installation.rst

Add 'sphinx_needs' and 'sphinx_codelinks' to your project's extensions list in conf.py to activate the package.

```python
extensions = [
    'sphinx_needs',
    'sphinx_codelinks'
]
```

--------------------------------

### Configure Sphinx Extensions

Source: https://github.com/useblocks/sphinx-codelinks/blob/main/docs/source/basics/quickstart.rst

Add 'sphinx_needs' and 'sphinx_codelinks' to your Sphinx extensions in conf.py. Configure source trace settings by pointing to a TOML file.

```python
extensions = [
    'sphinx_needs',
    'sphinx_codelinks'
]
src_trace_config_from_toml = "src_trace.toml"
```

--------------------------------

### Enable Local File System Links

Source: https://github.com/useblocks/sphinx-codelinks/blob/main/docs/source/components/configuration.rst

Enable the generation of local file system links to source code locations by setting 'set_local_url' to true in your TOML configuration.

```toml
[codelinks]
set_local_url = true
```

--------------------------------

### Run Specific Test Environment with Tox

Source: https://github.com/useblocks/sphinx-codelinks/blob/main/AGENTS.md

Run tests for a specific combination of Python, Sphinx, and sphinx-needs versions. Use `tox -a` to list available environments.

```bash
tox -e py312-sphinx8-needs5
```

--------------------------------

### Default Source Discovery Configuration

Source: https://github.com/useblocks/sphinx-codelinks/blob/main/docs/source/components/configuration.rst

Sets the default configuration for discovering source files, including the root directory, exclusion/inclusion patterns, gitignore respect, symbolic link following, and comment type.

```toml
[codelinks.projects.my_project.source_discover]
src_dir = "./"
exclude = []
include = []
gitignore = true
follow_links = false
comment_type = "cpp"
```

--------------------------------

### Python Project Source Discover Configuration

Source: https://github.com/useblocks/sphinx-codelinks/blob/main/docs/source/components/discover.rst

Configure source discovery specifically for a Python project, specifying directories and comment types.

```toml
[source_discover]
src_dir = "./my_package"
include = []
exclude = ["tests/**", "setup.py"]
comment_type = "python"
```

--------------------------------

### RST Documentation with src-trace Directive

Source: https://github.com/useblocks/sphinx-codelinks/blob/main/docs/source/basics/quickstart.rst

An RST file demonstrating the use of the 'src-trace' directive to generate links to source code. Specify the project name for linking.

```rst
.. note::
   This is a documentation file.

.. src-trace::
   :project: src

This directive will generate links to the source code based on the configuration.

```

--------------------------------

### Use src-trace Directive with File Option

Source: https://github.com/useblocks/sphinx-codelinks/blob/main/docs/source/components/directive.rst

Use the src-trace directive to trace needs from a specific file within a project. Ensure the project and file are correctly configured.

```rst
.. src-trace::
   :project: project_config
   :file: example.cpp
```

--------------------------------

### Run Test Cases with Tox

Source: https://github.com/useblocks/sphinx-codelinks/blob/main/docs/source/development/contributing.rst

Execute test cases locally using tox for a specific Python and Sphinx version combination.

```bash
tox -e py312-sphinx8
```

--------------------------------

### YAML Fixture with Custom Brackets and Fields

Source: https://github.com/useblocks/sphinx-codelinks/blob/main/tests/data/extraction/README.md

Defines a test case for C code extraction using custom start/end sequences and specific fields for needs. Includes custom markers for need IDs.

```yaml
custom_brackets_c:
  lang: c
  config:
    start_sequence: "[["
    end_sequence: "]]"
    field_split_char: ","
    needs_fields:
      - {name: title, type: str}
      - {name: id, type: str}
      - {name: type, type: str, default: impl}
      - {name: links, type: "list[str]", default: []}
    need_id_markers: ["@need-ids:"]   # optional; default ["@need-ids:"]
  source: |
    /* [[A Title, ID_1, impl, [REQ_1]]] */

```

--------------------------------

### Auto-Formatting with Ruff using Tox

Source: https://github.com/useblocks/sphinx-codelinks/blob/main/AGENTS.md

Apply automatic code formatting using Ruff via tox. This ensures consistent code style across the project.

```bash
tox -e ruff-fmt
```

--------------------------------

### Custom Source Directory Configuration

Source: https://github.com/useblocks/sphinx-codelinks/blob/main/docs/source/components/configuration.rst

Specifies a custom root directory for source file discovery, relative to the TOML configuration file's location.

```toml
[codelinks.projects.my_project.source_discover]
src_dir = "../src"
```

--------------------------------

### Use src-trace Directive with Directory Option

Source: https://github.com/useblocks/sphinx-codelinks/blob/main/docs/source/components/directive.rst

Use the src-trace directive to trace needs from all files within a specified directory. The directive will recursively search the directory.

```rst
.. src-trace::
   :project: project_config
   :directory: ./example
```

--------------------------------

### Configure Need ID Reference Extraction

Source: https://github.com/useblocks/sphinx-codelinks/blob/main/docs/source/components/configuration.rst

Set up markers to identify and extract Sphinx-Needs ID references from source code. This allows for linking needs based on specific marker strings.

```toml
[codelinks.projects.my_project.analyse.need_id_refs]
markers = ["@need-ids:"]

```

--------------------------------

### Specify TOML Configuration File

Source: https://github.com/useblocks/sphinx-codelinks/blob/main/docs/source/components/configuration.rst

Set the path to a TOML file containing CodeLinks configuration options in your Sphinx conf.py.

```python
# In conf.py
src_trace_config_from_toml = "codelinks.toml"
```

--------------------------------

### Run Tests with Coverage using Tox

Source: https://github.com/useblocks/sphinx-codelinks/blob/main/AGENTS.md

Execute tests and generate a code coverage report for the specified tox environment. The `-- --cov=sphinx_codelinks` flag enables coverage tracking.

```bash
tox -e py312-sphinx8-needs5 -- --cov=sphinx_codelinks
```

--------------------------------

### Configure src-trace in conf.py

Source: https://github.com/useblocks/sphinx-codelinks/blob/main/docs/source/components/directive.rst

Configure the src-trace directive by specifying the TOML file containing project tracing configurations in your Sphinx conf.py.

```python
src_trace_config_from_toml = "src_trace.toml"
```

--------------------------------

### Specify Output Directory

Source: https://github.com/useblocks/sphinx-codelinks/blob/main/docs/source/components/configuration.rst

Set the output directory for generated artifacts such as extracted markers and warnings.

```toml
[codelinks]
outdir = "output"
```

--------------------------------

### One-line comment with default type

Source: https://github.com/useblocks/sphinx-codelinks/blob/main/docs/source/components/oneline.rst

Demonstrates using a one-line comment where the 'type' field is omitted, allowing the default value ('implementation') to be used. The title is provided directly.

```c
// @ title here and default is used for type
```

--------------------------------

### Configure Sphinx CodeLinks

Source: https://github.com/useblocks/sphinx-codelinks/blob/main/README.md

Add 'sphinx_codelinks' to your Sphinx configuration file (conf.py). Optionally, specify a TOML file for source tracing configuration.

```python
extensions = ['sphinx_needs', 'sphinx_codelinks']
src_trace_config_from_toml = "codelinks.toml"
```

--------------------------------

### Sphinx Integration Flowchart

Source: https://github.com/useblocks/sphinx-codelinks/blob/main/AGENTS.md

A Mermaid flowchart illustrating the Sphinx integration flow, showing the sequence of build events and handler executions.

```mermaid
flowchart TB
    subgraph init["Initialization (config-inited)"]
        setup["setup() in __init__.py"]
        load_toml["load_config_from_toml()"]
        sn_options["update_sn_extra_options()"]
        sn_types["update_sn_types()"]
        check_config["check_sphinx_configuration()"]
    end

    subgraph prepare["Build Preparation"]
        builder_init["builder_inited: Copy CSS assets"]
        env_prepare["env-before-read-docs: prepare_env()"]
    end

    subgraph generate["Page Generation (html-collect-pages)"]
        gen_pages["generate_code_page()"]
        html_wrap["html_wrapper()"]
    end

    subgraph context["Page Context (html-page-context)"]
        add_css["add_custom_css()"]
    end

    subgraph finish["Build Finished"]
        warnings["emit_warnings()"]
        timing["debug.process_timing()"]
    end

    setup --> load_toml --> sn_options --> sn_types --> check_config
    check_config --> builder_init --> env_prepare
    env_prepare --> gen_pages --> html_wrap
    html_wrap --> add_css --> warnings --> timing

    style load_toml fill:#e1f5fe
    style gen_pages fill:#e1f5fe
    style html_wrap fill:#e1f5fe
```

--------------------------------

### Basic One-line RST Need in C Comment

Source: https://github.com/useblocks/sphinx-codelinks/blob/main/docs/source/components/analyse.rst

This C comment shows a simplified syntax for creating Sphinx-Needs items directly in code. It uses a single line to define the need's description, ID, type, and links.

```c
// @Function Implementation, IMPL_001, impl, [REQ_001, REQ_002]

```

--------------------------------

### TOML Configuration for Source Trace

Source: https://github.com/useblocks/sphinx-codelinks/blob/main/docs/source/basics/quickstart.rst

This TOML file defines the configuration for the src-trace directive, specifying how source code links should be generated.

```toml
[tool.sphinx-codelinks.source]
base_path = "/usr/src/app/"
show_root_heading = true

[tool.sphinx-codelinks.git]
url = "https://github.com/useblocks/sphinx-codelinks/blob/main/"

```

--------------------------------

### Enable Remote Repository Links

Source: https://github.com/useblocks/sphinx-codelinks/blob/main/docs/source/components/configuration.rst

Enable the generation of remote repository links to source code locations by setting 'set_remote_url' to true in your TOML configuration.

```toml
[codelinks]
set_remote_url = true
```

--------------------------------

### Advanced Source Discover Filtering

Source: https://github.com/useblocks/sphinx-codelinks/blob/main/docs/source/components/discover.rst

Utilize advanced filtering options including include/exclude patterns, gitignore, and symbolic link following for source discovery.

```toml
[source_discover]
src_dir = "./"
include = []
exclude = ["src/legacy/**", "**/*_test.cpp"]
gitignore = true
follow_links = false
comment_type = "cpp"
```

--------------------------------

### Basic src-trace Directive Usage

Source: https://github.com/useblocks/sphinx-codelinks/blob/main/docs/source/basics/quickstart.rst

The src-trace directive is used within documentation to create links to the corresponding source code. The 'project' option specifies the project context for linking.

```rst
.. src-trace::
   :project: src
```

--------------------------------

### Check Code Typing with Tox

Source: https://github.com/useblocks/sphinx-codelinks/blob/main/docs/source/development/contributing.rst

Run the mypy type checker locally to ensure code is well-typed, mirroring CI checks.

```bash
tox -e mypy
```

--------------------------------

### Including Specific Files

Source: https://github.com/useblocks/sphinx-codelinks/blob/main/docs/source/components/configuration.rst

Defines glob patterns to explicitly include files for source discovery. This overrides other filtering rules for matched files.

```toml
[codelinks.projects.my_project.source_discover]
include = [
    "src/**/*.cpp",
    "src/**/*.h",
    "include/**/*.hpp"
]
```

--------------------------------

### Define Remote URL Pattern for a Project

Source: https://github.com/useblocks/sphinx-codelinks/blob/main/docs/source/components/configuration.rst

Define the URL pattern for generating links to remote source code repositories for a specific project. This pattern uses placeholders for commit, path, and line number.

```toml
[codelinks.projects.my_project]
remote_url_pattern = "https://github.com/user/repo/blob/{commit}/{path}#L{line}"
```

--------------------------------

### YAML Fixture Configuration

Source: https://github.com/useblocks/sphinx-codelinks/blob/main/tests/data/extraction/README.md

Defines a test case for C++ code extraction with default configuration. Specifies language, configuration type, and the source code.

```yaml
default_oneliner_cpp:
  lang: cpp                 # cpp | c | python | csharp | rust | yaml | go | jsonc
  config: default          # "default", or an inline config block (see below)
  source: |
    // @My Title, IMPL_1, impl, [REQ_1]
    void f() {}

```

--------------------------------

### Running Declarative Extraction Tests

Source: https://github.com/useblocks/sphinx-codelinks/blob/main/tests/data/extraction/README.md

Command to execute the declarative extraction tests using pytest. This command runs all defined fixtures and compares their output against committed snapshots.

```bash
# run the declarative extraction tests
python -m pytest tests/test_extraction_fixtures.py

```

--------------------------------

### Run Specific Test File with Tox

Source: https://github.com/useblocks/sphinx-codelinks/blob/main/AGENTS.md

Execute tests within a particular file for a specified tox environment. This is useful for isolating test failures.

```bash
tox -e py312-sphinx8-needs5 -- tests/test_analyse.py
```

--------------------------------

### Run Specific Test Function with Tox

Source: https://github.com/useblocks/sphinx-codelinks/blob/main/AGENTS.md

Target a single test function within a specific file and tox environment for focused debugging.

```bash
tox -e py312-sphinx8-needs5 -- tests/test_analyse.py::test_function_name
```

--------------------------------

### Updating Snapshots for Extraction Tests

Source: https://github.com/useblocks/sphinx-codelinks/blob/main/tests/data/extraction/README.md

Command to update snapshots after modifying fixtures or the extraction logic. Use this to accept changes and commit new expected outputs.

```bash
# review + accept snapshot changes after editing fixtures or the extractor
python -m pytest tests/test_extraction_fixtures.py --snapshot-update

```

--------------------------------

### Excluding Files and Directories

Source: https://github.com/useblocks/sphinx-codelinks/blob/main/docs/source/components/configuration.rst

Defines glob patterns to exclude specific files and directories from source discovery, such as build artifacts or temporary files.

```toml
[codelinks.projects.my_project.source_discover]
exclude = [
    "build/**"
    "*.tmp"
    "tests/fixtures/**"
    "vendor/third_party/**"
]
```

--------------------------------

### Normalized JSON Snapshot Structure

Source: https://github.com/useblocks/sphinx-codelinks/blob/main/tests/data/extraction/README.md

The expected output structure for extracted code, normalized into JSON format. Includes fields for needs, need references, marked RST, and warnings.

```json
{
  "needs":      [{"id": "", "title": "", "type": "", "links": {"field": ["..."]}, "line": 1}],
  "need_refs":  [{"need_id": "", "line": 1}],
  "marked_rst": [{"content": "", "start_line": 1, "end_line": 1}],
  "warnings":   [{"kind": "too_many_fields", "line": 1}]
}

```

--------------------------------

### Linting with Ruff Check using Tox

Source: https://github.com/useblocks/sphinx-codelinks/blob/main/AGENTS.md

Run Ruff in check-only mode to identify linting issues without making changes. This is part of the code quality checks.

```bash
tox -e ruff-check
```

--------------------------------

### Python Comment Type Configuration

Source: https://github.com/useblocks/sphinx-codelinks/blob/main/docs/source/components/configuration.rst

Sets the comment type to 'python', enabling parsing of Python-style comments and discovery of Python source files.

```toml
[codelinks.projects.my_project.source_discover]
comment_type = "python"
```

--------------------------------

### TOML needs_fields Configuration

Source: https://github.com/useblocks/sphinx-codelinks/blob/main/docs/source/components/oneline.rst

Defines the fields for needs using TOML syntax, specifying names, optional data types like 'list[str]', and default values. This configuration is used to parse one-line comment style needs.

```toml
[[
 needs_fields ]]
 name = "title"
```

```toml
[[
 needs_fields ]]
 name = "links"
 type = "list[str]"
```

```toml
needs_fields = [
   { name = "title" },
   { name = "id" },
   { name = "type", default = "impl" },
   { name = "links", type = "list[str]", default = [] },
]
```

```toml
needs_fields = [
   { name = "title" },
   { name = "type", default = "implementation" }
]
```

--------------------------------

### Python needs_fields Configuration

Source: https://github.com/useblocks/sphinx-codelinks/blob/main/docs/source/components/oneline.rst

Defines the fields for needs, including their names, data types (like 'list[str]'), and default values. This configuration is used to parse one-line comment style needs.

```python
{
    "name": "title"
}
```

```python
{
    "name": "title",
    "type": "str"
}
```

```python
{
    "name": "links",
    "type": "list[str]"
}
```

```python
[
   {"name": "title"},
   {"name": "id"},
   {"name": "type", "default": "impl"},
   {"name": "links", "type": "list[str]", "default": []},
]
```

```python
[
   {
      "name": "title"
   },
   {
      "name": "type",
      "default": "implementation"
   },
]
```

--------------------------------

### Update Snapshot Tests with Tox

Source: https://github.com/useblocks/sphinx-codelinks/blob/main/AGENTS.md

Update snapshot test fixtures for a given tox environment. Use this command when test outputs change legitimately.

```bash
tox -e py312-sphinx8-needs5 -- --snapshot-update
```

--------------------------------

### JSON Markers from Analyse Command

Source: https://github.com/useblocks/sphinx-codelinks/blob/main/docs/source/components/write.rst

This JSON represents the extracted markers from the 'analyse' command, containing file paths, remote URLs, source code mappings, and identified need IDs.

```json
{
    "my_project": [
        {
            "filepath": "/home/demo/git_repo/ub/sphinx-codelinks/tests/data/need_id_refs/dummy_1.cpp",
            "remote_url": "https://github.com/useblocks/sphinx-codelinks/blob/951e40e7845f06d5cfc4ca20ebb984308fdaf985/tests/data/need_id_refs/dummy_1.cpp#L3",
            "source_map": {
                "start": {"row": 2, "column": 13},
                "end": {"row": 2, "column": 51}
            },
            "tagged_scope": "void dummy_func1(){\n     //...\n }",
            "need_ids": ["NEED_001", "NEED_002", "NEED_003", "NEED_004"],
            "marker": "@need-ids:",
            "type": "need-id-refs"
        },
    ],
}
```

--------------------------------

### Convert One-Line Comment to RST Directive

Source: https://github.com/useblocks/sphinx-codelinks/blob/main/docs/source/components/configuration.rst

Illustrates the transformation of a source code one-line comment into a Sphinx-Needs RST directive. The 'type' and 'title' fields are mandatory and must be configured.

```cpp
// @Function Bar, IMPL_4, impl, [SPEC_1, SPEC_2]

```

```rst
.. impl:: Function Bar
   :id: IMPL_4
   :links: SPEC_1, SPEC_2

```

--------------------------------

### Commit Message Keywords

Source: https://github.com/useblocks/sphinx-codelinks/blob/main/AGENTS.md

A list of keywords to use in commit messages to categorize changes. These keywords help in understanding the nature of the commit at a glance.

```text
✨ NEW: – New feature
🐛 FIX: – Bug fix
👌 IMPROVE: – Improvement (no breaking changes)
‼️ BREAKING: – Breaking change
📚 DOCS: – Documentation
🔧 MAINTAIN: – Maintenance changes only (typos, etc.)
🧪 TEST: – Tests or CI changes only
♻️ REFACTOR: – Refactoring
```

--------------------------------

### Commit Message Format

Source: https://github.com/useblocks/sphinx-codelinks/blob/main/AGENTS.md

Use this format for commit messages, including an emoji, keyword, concise summary, and optional detailed explanation. Keywords indicate the type of change.

```text
<EMOJI> <KEYWORD>: Summarize in 72 chars or less (#<PR>)

Optional detailed explanation.
```

--------------------------------

### Configure One-Line Comment Style

Source: https://github.com/useblocks/sphinx-codelinks/blob/main/docs/source/components/configuration.rst

Define how one-line comments in source code are parsed into Sphinx-Needs. Specifies start/end sequences, field separators, and mandatory fields like title and ID.

```toml
[codelinks.projects.my_project.analyse.oneline_comment_style]
start_sequence = "@"
end_sequence = "\n"  # Platform-specific line ending
field_split_char = ","
needs_fields = [
      { name = "title", type = "str" },
      { name = "id", type = "str" },
      { name = "type", type = "str", default = "impl" },
      { name = "links", type = "list[str]", default = [] },
]

```

--------------------------------

### Specify Local URL Field Name

Source: https://github.com/useblocks/sphinx-codelinks/blob/main/docs/source/components/configuration.rst

Define the custom field name to be used for local source code links when 'set_local_url' is enabled.

```toml
[codelinks]
local_url_field = "local-url"
```

--------------------------------

### Sphinx Event Handlers Table

Source: https://github.com/useblocks/sphinx-codelinks/blob/main/AGENTS.md

This table lists the Sphinx events and their corresponding handlers used by the extension. It details the purpose of each handler in the build process.

```markdown
| Event                  | Handler                        | Purpose                                                              |
| ---------------------- | ------------------------------ | -------------------------------------------------------------------- |
| `config-inited`        | `load_config_from_toml()`      | Load configuration from TOML file if specified                       |
| `config-inited`        | `update_sn_extra_options()`    | Register sphinx-needs extra options (project, file, directory, URLs) |
| `config-inited`        | `update_sn_types()`            | Add `srctrace` need type to sphinx-needs                             |
| `config-inited`        | `check_sphinx_configuration()` | Validate configuration and raise errors                              |
| `builder-inited`       | `builder_inited()`             | Copy CSS assets to output directory                                  |
| `env-before-read-docs` | `prepare_env()`                | Initialize timing measurements and debug filters                     |
| `html-collect-pages`   | `generate_code_page()`         | Generate HTML pages for traced source files                          |
| `html-page-context`    | `add_custom_css()`             | Inject custom CSS for source tracing UI                              |
| `build-finished`       | `emit_warnings()`              | Emit collected warnings from analysis                                |
| `build-finished`       | `debug.process_timing()`       | Output timing measurements if enabled                                |
```

--------------------------------

### Specify Explicit Git Repository Root

Source: https://github.com/useblocks/sphinx-codelinks/blob/main/docs/source/components/configuration.rst

Set `git_root` to an absolute path to explicitly define the Git repository root. This is useful for Bazel builds or deeply nested configurations where auto-detection might fail.

```toml
[codelinks.projects.my_project.analyse]
git_root = "/absolute/path/to/repo"
```

--------------------------------

### Update Syrupy Snapshots

Source: https://github.com/useblocks/sphinx-codelinks/blob/main/docs/source/development/contributing.rst

Update syrupy snapshots for snapshot testing by running pytest with the --snapshot-update flag.

```bash
pytest tests/ --snapshot-update
```

--------------------------------

### Enable Need ID Extraction from Comments

Source: https://github.com/useblocks/sphinx-codelinks/blob/main/docs/source/components/configuration.rst

Set `get_need_id_refs` to `true` to enable the extraction of need IDs from source code comments. This allows `SourceAnalyse` to parse comments for specific markers indicating need IDs.

```toml
[codelinks.projects.my_project.analyse]
get_need_id_refs = true
```

--------------------------------

### C++ Source Code with Needs Comment

Source: https://github.com/useblocks/sphinx-codelinks/blob/main/docs/source/basics/quickstart.rst

A C++ source file containing a one-line comment that defines a Sphinx-Needs item, which can be linked by CodeLinks.

```cpp
// NEEDS: id=dummy_cpp_file, title=Dummy C++ File, status=done
int main() {
    return 0;
}

```

--------------------------------

### Analyse Tool Output for C++ RST Extraction

Source: https://github.com/useblocks/sphinx-codelinks/blob/main/docs/source/components/analyse.rst

This JSON output represents the data extracted by the analyse tool from the C++ code. It includes file paths, remote URLs, source code mapping, the tagged code scope, and the extracted RST content.

```json
[
    {
        "filepath": "marked_rst/dummy_1.cpp",
        "remote_url": "https://github.com/useblocks/sphinx-codelinks/blob/26b301138eef25c5130518d96eaa7a29a9c6c9fe/marked_rst/dummy_1.cpp#L4",
        "source_map": {
            "start": { "row": 3, "column": 8 },
            "end": { "row": 3, "column": 61 }
        },
        "tagged_scope": "void dummy_func1(){\n     //...\n }",
        "rst": ".. impl:: implement dummy function 1\n   :id: IMPL_71\n",
        "type": "rst"
    },
    {
        "filepath": "marked_rst/dummy_1.cpp",
        "remote_url": "https://github.com/useblocks/sphinx-codelinks/blob/26b301138eef25c5130518d96eaa7a29a9c6c9fe/marked_rst/dummy_1.cpp#L14",
        "source_map": {
            "start": { "row": 13, "column": 7 },
            "end": { "row": 13, "column": 40 }
        },
        "tagged_scope": "int main() {\n   std::cout << \"Starting demo_1...\" << std::endl;\n   dummy_func1();\n   std::cout << \"Demo_1 finished.\" << std::endl;\n   return 0;\n }",
        "rst": "..impl:: implement main function ",
        "type": "rst"
    }
]

```

--------------------------------

### Disable Gitignore for Source Discovery

Source: https://github.com/useblocks/sphinx-codelinks/blob/main/docs/source/components/configuration.rst

Set `gitignore` to `false` to disable the use of ignore files during source file discovery. This will cause all matching files to be processed, regardless of ignore rules.

```toml
[codelinks.projects.my_project.source_discover]
gitignore = false
```

--------------------------------

### Extract RST from C++ Comments

Source: https://github.com/useblocks/sphinx-codelinks/blob/main/docs/source/components/analyse.rst

This C++ code demonstrates multi-line and single-line RST blocks within comments. The analyse tool can extract these blocks along with their associated code scopes.

```cpp
#include <iostream>

/*
@rst
.. impl:: implement dummy function 1
:id: IMPL_71
@endrst
*/
void dummy_func1(){
    //...
}

// @rst..impl:: implement main function @endrst
int main() {
    std::cout << "Starting demo_1..." << std::endl;
    dummy_func1();
    std::cout << "Demo_1 finished." << std::endl;
    return 0;
}

```

--------------------------------

### Specify Remote URL Field Name

Source: https://github.com/useblocks/sphinx-codelinks/blob/main/docs/source/components/configuration.rst

Define the custom field name to be used for remote source code links when 'set_remote_url' is enabled.

```toml
[codelinks]
remote_url_field = "remote-url"
```

--------------------------------

### Escaping Backslash in C and reStructuredText

Source: https://github.com/useblocks/sphinx-codelinks/blob/main/docs/source/components/oneline.rst

Illustrates how to represent a literal backslash character in C comments and reStructuredText directives by using a double backslash.

```c
// @ title\\ 3, IMPL_3 , impl, [[\[SPEC\,_1\]]]
```

```rst
.. impl:: title\ 3
   :id: IMPL_3
   :links: [SPEC,_1]
```

--------------------------------

### Disable One-Line Need Extraction from Comments

Source: https://github.com/useblocks/sphinx-codelinks/blob/main/docs/source/components/configuration.rst

Set `get_oneline_needs` to `false` to disable the extraction of one-line needs from source code comments. When enabled, `SourceAnalyse` parses comments for simplified patterns representing needs.

```toml
[codelinks.projects.my_project.analyse]
get_oneline_needs = false
```

--------------------------------

### Generated reStructuredText with needextend Directives

Source: https://github.com/useblocks/sphinx-codelinks/blob/main/docs/source/components/write.rst

This reStructuredText output is generated by the 'write rst' command, utilizing 'needextend' directives for each identified need ID, including the remote URL for source code linking.

```rst
.. needextend:: NEED_001
       :remote-url: https://github.com/useblocks/sphinx-codelinks/blob/951e40e7845f06d5cfc4ca20ebb984308fdaf985/tests/data/need_id_refs/dummy_1.cpp#L3

.. needextend:: NEED_002
       :remote-url: https://github.com/useblocks/sphinx-codelinks/blob/951e40e7845f06d5cfc4ca20ebb984308fdaf985/tests/data/need_id_refs/dummy_1.cpp#L3

.. needextend:: NEED_003
       :remote-url: https://github.com/useblocks/sphinx-codelinks/blob/951e40e7845f06d5cfc4ca20ebb984308fdaf985/tests/data/need_id_refs/dummy_1.cpp#L3

.. needextend:: NEED_004
       :remote-url: https://github.com/useblocks/sphinx-codelinks/blob/951e40e7845f06d5cfc4ca20ebb984308fdaf985/tests/data/need_id_refs/dummy_1.cpp#L3

```