### Install Sphinx-Immaterial Theme

Source: https://github.com/useblocks/sphinx-test-reports/blob/master/docs/ub_theme/README.md

Installs the Sphinx-Immaterial theme using pip and activates it in the Sphinx configuration. Ensure Sphinx-Immaterial is installed before proceeding.

```bash
pip install sphinx-immaterial

extensions = ["sphinx_immaterial"]
html_theme = "sphinx_immaterial"
```

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

### Complete conf.py Configuration Example

Source: https://github.com/useblocks/sphinx-test-reports/blob/master/docs/ub_theme/README.md

An example of a complete conf.py file demonstrating the integration of Useblocks theme settings with Sphinx-Immaterial. It includes path configuration, theme options, and static file paths.

```python
import sys
import os

sys.path.append(os.path.abspath("."))

from ub_theme.conf import html_theme_options

extensions = [
    "sphinx_immaterial",
]

templates_path = ["_templates", "ub_theme/templates"]

html_theme = "sphinx_immaterial"
html_theme_options = html_theme_options

# You can add other Sphinx-Immaterial theme options like below
other_options = {
    "repo_url": "https://github.com/useblocks/useblocks-theme",
    "repo_name": "useblocks-theme",
    "repo_type": "github",
}
html_theme_options.update(other_options)

html_static_path = ["_static", "ub_theme/css", "ub_theme/js"]
html_css_files = ["ub-theme.css"]
html_js_files = ["ub-theme.js"]

```

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

### Install Development Dependencies with uv (Bash)

Source: https://github.com/useblocks/sphinx-test-reports/blob/master/CONTRIBUTING.md

Installs all necessary dependencies for local development using the uv package manager. This command synchronizes all groups and extras, ensuring the environment is ready for development.

```bash
uv sync --all-groups --all-extras
```

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

### Install Package Metadata (JSON)

Source: https://github.com/useblocks/sphinx-test-reports/blob/master/tests/doc_test/env_report_doc_default/index.md

Provides metadata for the installation package, including the base filename, MD5 hash, and SHA256 hash. This information is crucial for verifying the integrity and authenticity of the downloaded package.

```json
{
    "basename": "project_1.2.0.zip",
    "md5": "df03855c61c10ddd32f2c888856cc51e",
    "sha256": "576f9f616a18bc74404a0f241c96d9e3c75f03f091f8981495598d0c6dc25c41"
}
```

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

### Install pre-commit Hook (Bash)

Source: https://github.com/useblocks/sphinx-test-reports/blob/master/CONTRIBUTING.md

Installs the pre-commit framework as a Git hook. This automatically runs pre-commit checks before each commit, helping to maintain code quality and consistency.

```bash
pre-commit install
```

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

### Visualize Test Element Relationships (RST)

Source: https://github.com/useblocks/sphinx-test-reports/blob/master/tests/doc_test/basic_doc/examples/index.md

This directive generates a flow diagram showing the relationships between test elements. The first example filters for needs related to a specific ID ('PYTEST01') or linked from it. The second example displays all 'testfile' and 'testsuite' types within sections containing 'Examples'.

```rst
.. needflow::
   :filter: id == 'PYTEST01' or 'PYTEST01' in links
```

```rst
.. needflow::
   :types: testfile, testsuite
   :filter: 'Examples' in sections
```

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

### JSON Example for Selector Demonstration

Source: https://github.com/useblocks/sphinx-test-reports/blob/master/tests/doc_test/env_report_warnings/configuration.md

A sample JSON structure used to illustrate how the 'selector list' in 'tr_json_mapping' works. The example shows nested objects and arrays, demonstrating how to traverse the structure to access specific values.

```json
{
    "level_1": {
        "level_2": [
            {"value": "Hello!"}
            {"value": "Bye Bye!"}
        ]
    }
}
```

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

### Display All Test Files and Suites with needflow (RST)

Source: https://github.com/useblocks/sphinx-test-reports/blob/master/tests/doc_test/many_testsuites_doc/examples/index.md

This `needflow` directive displays all needs of types 'testfile' and 'testsuite' that are within the 'Examples' section. It demonstrates how to use the `types` and `filter` options to show all test artifacts.

```rst
.. needflow::
   :types: testfile, testsuite
   :filter: 'Examples' in sections

```

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

### Sphinx LaTeX Document Build Failure Example

Source: https://github.com/useblocks/sphinx-test-reports/blob/master/tests/doc_test/env_report_warnings/directives/test_report.md

This snippet details a failed test case for building a LaTeX document using 'lualatex'. The test, 'test_build_latex_doc[lualatex-howto]', resulted in a failure with a reported execution time.

```xml
<testcase name="test_build_latex_doc" classname="tests.test_build" time="0.9610209465026855" result="failure">
<properties>
<property name="case_parameter" value="lualatex-howto"/>
</properties>
</testcase>
```

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

### List Installed Python Packages

Source: https://github.com/useblocks/sphinx-test-reports/blob/master/tests/doc_test/env_report_doc_default/index.md

This JSON snippet displays a list of Python packages installed for the project, including their version numbers. This is useful for understanding the project's dependencies and ensuring environment consistency.

```json
[
    "arrow==0.10.0",
    "atomicwrites==1.2.1",
    "attrs==18.2.0",
    "binaryornot==0.4.4",
    "blinker==1.4",
    "brotlipy==0.7.0",
    "certifi==2018.4.16",
    "cffi==1.11.5",
    "chardet==3.0.4",
    "click==6.7",
    "cookiecutter==1.5.1",
    "coverage==4.5.2",
    "decorator==4.3.0",
    "docutils==0.14",
    "envparse==0.2.0",
    "project==0.1.0",
    "filelock==3.0.10",
    "Flask==1.0.2",
    "future==0.16.0",
    "groundwork==0.1.13",
    "gw-utils==0.2.3",
    "httpbin==0.7.0",
    "idna==2.6",
    "itsdangerous==1.1.0",
    "Jinja2==2.9.6",
    "jinja2-time==0.2.0",
    "jsonschema==2.6.0",
    "lxml==4.0.0",
    "MarkupSafe==1.0",
    "more-itertools==4.3.0",
    "nose==1.3.7",
    "pathlib==1.0.1",
    "pathlib2==2.3.2",
    "pluggy==0.8.0",
    "poyo==0.4.1",
    "py==1.7.0",
    "pycparser==2.19",
    "pyelftools===0.24-st1",
    "pytest==4.0.0",
    "pytest-cov==2.6.0",
    "pytest-runner==4.2",
    "python-dateutil==2.6.1",
    "PyYAML==3.13",
    "raven==6.9.0",
    "requests==2.18.4",
    "six==1.11.0",
    "svn==0.3.45",
    "toml==0.10.0",
    "tox==3.5.3",
    "typing==3.6.6",
    "urllib3==1.22",
    "virtualenv==16.1.0",
    "Werkzeug==0.14.1",
    "whichcraft==0.4.1",
    "yamldirs==1.1.3"
]
```

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

### Documenting Pytest Test Data with test-file Directive

Source: https://github.com/useblocks/sphinx-test-reports/blob/master/tests/doc_test/needs_linking/directives/test_file.md

This example shows how to document test data generated by pytest using the `test-file` directive. It includes the file path, a unique ID, and a link to another test file (TESTFILE_1).

```rst
.. test-file:: pytest test data
   :file: ../tests/doc_test/utils/pytest_data.xml
   :id: TESTFILE_2
   :links: TESTFILE_1

   This test-file was created by `pytest <https://docs.pytest.org/en/latest/>`_.

```

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

### JSON Selector Example

Source: https://github.com/useblocks/sphinx-test-reports/blob/master/docs/configuration.md

Illustrates how to use a selector list to navigate a JSON structure and extract specific values. Selectors can be strings for keys or integers for array indices.

```default
["level_1", "level_2", 1, "value"]
```

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

### Create Test Dependency Flow Chart with Sphinx-Needs

Source: https://context7.com/useblocks/sphinx-test-reports/llms.txt

Demonstrates using the `needflow` directive to visualize test dependencies. This example filters tests tagged with 'TESTFILE_001' and enables the display of link names in the flow chart.

```rst
.. needflow::
   :filter: "TESTFILE_001" in tags
   :show_link_names:
```

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

### Default: Sphinx Build System Output

Source: https://github.com/useblocks/sphinx-test-reports/blob/master/docs/directives/test_report.md

This snippet provides the system output from a Sphinx documentation build process. It details the test environment, including the root directory, builder type, source directory, and output directory. It also indicates the status and warning streams were captured.

```text
# testroot: root
# builder: html
# srcdir: /tmp/root
# outdir: /tmp/root/_build/html
# status:
# warning:
```

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

### Documenting Common XML Test Data with test-file Directive

Source: https://github.com/useblocks/sphinx-test-reports/blob/master/tests/doc_test/needs_linking/directives/test_file.md

This example demonstrates how to use the `test-file` directive to document a test file containing common XML test data. It specifies the file path and a unique ID. Options not set will default to '-1'.

```rst
.. test-file:: common xml test data
   :file: ../tests/doc_test/utils/xml_data.xml
   :id: TESTFILE_1

   This test-file has very common data.
   Some options are net set, therefore their value is ``-1``

```

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

### Default test-env output example

Source: https://github.com/useblocks/sphinx-test-reports/blob/master/tests/doc_test/basic_doc/directives/test_env.md

This example shows the default usage of the test-env directive, specifying a JSON file and filtering by environment and specific data fields.

```rst
.. test-env: my/path/to/tox-envreport-short.json
   :env: py27
   :data: name, host, installed_packages
```

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

### Documenting Nose Test Data with test-file Directive

Source: https://github.com/useblocks/sphinx-test-reports/blob/master/tests/doc_test/needs_linking/directives/test_file.md

This example illustrates documenting test data generated by nosetest using the `test-file` directive. It includes file path, ID, links, status, tags, and the collapse option. Setting `collapse` to FALSE displays the data directly.

```rst
.. test-file:: nose test data
   :file: ../tests/doc_test/utils/nose_data.xml
   :id: TESTFILE_3
   :links: TESTFILE_1
   :status: open
   :tags: pytest, data, awesome
   :collapse: FALSE

   This test-file was created by `nosetest <https://nose.readthedocs.io/en/latest/>`_.

   ``collapse`` was set to False, therefor we see its data directly.
   Also ``status`` and ``tags`` are set.

```

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

### Pytest Flake8 Output Example

Source: https://github.com/useblocks/sphinx-test-reports/blob/master/docs/examples/index.md

This snippet shows an example of output from pytest_flake8, indicating that files have previously passed FLAKE8 checks. It highlights the file path and the success message.

```default
/home/daniel/workspace/sphinx/sphinx-test-reports/.tox/py27-sphinx15/local/lib/python2.7/site-packages/pytest_flake8.py:106: <py._xmlgen.raw object at 0x7fd5a84bf090>
file(s) previously passed FLAKE8 checks
```

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

### Example: JSON Selector for Nested Data

Source: https://github.com/useblocks/sphinx-test-reports/blob/master/tests/doc_test/many_testsuites_doc/configuration.md

This example shows a JSON structure and a corresponding selector list used in `tr_json_mapping` to access a specific value within nested JSON objects and arrays.

```json
{
    "level_1": {
        "level_2": [
            {"value": "Hello!"}
            {"value": "Bye Bye!"}
        ]
    }
}
```

```default
["level_1", "level_2", 1, "value"]
```

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

### Clone Useblocks Theme Repository

Source: https://github.com/useblocks/sphinx-test-reports/blob/master/docs/ub_theme/README.md

Downloads the Useblocks theme files from the GitHub repository using Git. This command should be executed in your project's documentation directory.

```bash
cd docs
git clone https://github.com/useblocks/useblocks-theme.git
```

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

### Sphinx test-report Directive Example

Source: https://github.com/useblocks/sphinx-test-reports/blob/master/docs/directives/test_report.md

This reStructuredText snippet demonstrates the usage of the `test-report` directive in Sphinx. It allows for the inclusion of test execution results from a specified XML file, with options to tag and link the report.

```rst
.. test-report:: My Report
   :id: REPORT
   :file: ../tests/doc_test/utils/pytest_sphinx_data_short.xml
   :tags: my_report, awesome
   :links: SPEC_001

.. spec:: Example specification
   :id: SPEC_001

   Used as simple link target. See Sphinx-Needs for details.

```

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

### Raw Test Environment Output Example (JSON)

Source: https://github.com/useblocks/sphinx-test-reports/blob/master/docs/directives/test_env.md

This JSON represents the raw output for a specific test environment, as displayed when using the ':raw:' option with the test-env directive. It includes details like 'host', 'installed_packages', and 'name'.

```json
{
    "host": "user_abc",
    "installed_packages": [
        "arrow==0.10.0",
        "atomicwrites==1.2.1"
    ],
    "name": "py35"
}
```

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

### LaTeX Build Failure with LuaTeX

Source: https://github.com/useblocks/sphinx-test-reports/blob/master/docs/directives/test_report.md

This snippet details a build failure when using the 'lualatex' engine for LaTeX output in Sphinx. The error indicates that a required module 'luaotfload-main' was not found, leading to the build process exiting with a non-zero return code. It also highlights warnings about duplicate section number assignments and unincluded documents.

```default
app = <SphinxTestApp buildername='latex'>, status = <_io.StringIO object at<br/>0x7ff4c662a438>, warning = <_io.StringIO object at 0x7ff4c662a678><br/>engine = 'lualatex', docclass = 'howto'<br/><br/>@skip_if_requested<br/>@skip_if_stylefiles_notfound<br/>print(stdout)<br/>print(stderr)<br/>> assert False, '%s exited with return code %s' % (<br/>app.config.latex_engine, p.returncode)<br/>E AssertionError: lualatex exited with return code 1<br/>E assert False<br/><br/>tests/test_build_latex.py:86: AssertionError<br/>```<br/><br/>**System-out**:<br/><br/>```default<br/>b"This is LuaTeX, Version 1.0.4 (TeX Live 2017/Debian) \n restricted system commands<br/>enabled.<br/>(./lualatex/SphinxTests.tex<br/>LaTeX2e <2017-04-15><br/>[\directlua]:1: module 'luaotfload-main'<br/>not found:<br/>\tno field package.preload['luaotfload-main']<br/>\t[kpse lua searcher] file not found:<br/>#x1B[31m/tmp/root/contents.txt:10: WARNING: extensions is already assigned section numbers (nested numbered<br/>toctree?)#x1B[39;49;00m<br/>#x1B[31m/tmp/root/robots.txt: WARNING: document isn't included in any toctree#x1B[39;49;00m<br/>``` 
```

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

### Example RST for Test Report Template

Source: https://github.com/useblocks/sphinx-test-reports/blob/master/docs/configuration.md

An example of a reStructuredText template used for visualizing test case reports. It demonstrates how to include file information, use directives like 'needtable' to display test cases, and provide statistics for suites and cases.

```rst
**Test file**: {file}

**Template used**: {template_path}

**Imported data**

.. {file_type}:: {title}
   :id: {id}{links_string}
   :tags: {tags}
   :file: {file}
   :auto_suites:
   :auto_cases:

   {content}


**Test cases**:

.. needtable::
   :filter: '{id}' in tags and type == '{case_need}'
   :columns: id, title, result
   :style_row: tr_[[copy('result')]]

**Failed test cases**:

.. needtable::
   :filter: '{id}' in tags and 'failure' == result
   :columns: id, title, result
   :style_row: tr_[[copy('result')]]

**Skipped test cases**:

.. needtable::
   :filter: '{id}' in tags and 'skipped' == result
   :columns: id, title, result
   :style_row: tr_[[copy('result')]]


**Statistics**

| Test suites: :need_count:`<ctrl63>
```

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

### Visualize Test Data Flow with needflow (RST)

Source: https://github.com/useblocks/sphinx-test-reports/blob/master/tests/doc_test/many_testsuites_doc/examples/index.md

The `needflow` directive visualizes the relationships between test-related needs. This example shows how to filter the flow based on a specific need ID ('PYTEST01') or needs linked to it. It's useful for tracing dependencies.

```rst
.. needflow::
   :filter: id == 'PYTEST01' or 'PYTEST01' in links

```