Metadata-Version: 2.1
Name: sphinx_needs_data_explorer
Version: 0.9.0
Summary: Sphinx-needs-data-explorer is a Sphinx extension to visualize Sphinx-Needs data
Home-page: https://github.com/mi-parkes/sphinx_needs_data_explorer
License: MIT
Author: Michael Parkes
Author-email: mparkes@post.cz
Requires-Python: >=3.12,<4.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Requires-Dist: Sphinx (>=6.1.3)
Project-URL: Documentation, https://mi-parkes.github.io/sphinx_needs_data_explorer/
Project-URL: Repository, https://github.com/mi-parkes/sphinx_needs_data_explorer
Description-Content-Type: text/markdown


## About

<br>

The `sphinx_needs_data_explorer` is a web application written in HTML, CSS, and JavaScript, provided as a [Sphinx](https://www.sphinx-doc.org/en/master/index.html) extension. It enhances the interactivity of your Sphinx-generated documentation by enabling you to explore <a href="[needs.json](https://mi-parkes.github.io/sphinx-needs-data-explorer/needs.json)">Sphinx-Needs-Data</a> generated by the [Sphinx-Needs-Extension](https://www.sphinx-needs.com).

## Goals and Realization

<br>

![](https://raw.githubusercontent.com/mi-parkes/sphinx-needs-data-explorer/6d9afc22473bdcf64cf12f92188f1c4203ce3ae5/doc/source/images/sphinx_needs_data_explorer.svg)

<br>

## Features

### Three Sphinx-Needs Data View Perspectives

#### `Network-View`
In Network-View-Perspective you can see how sphinx-needs data are interconnected in data networks.

You can choose which **data context** to see
- incoming connections from in-neighbours
- outgoing connections from out-neighbours
- incoming and outgoing connections

You can choose **network layout**
- hierarchical bottom-up
- hierarchical right-to-left
- hierarchical with repulsion

![](https://raw.githubusercontent.com/mi-parkes/sphinx-needs-data-explorer/6d9afc22473bdcf64cf12f92188f1c4203ce3ae5/doc/source/images/network-perspective.jpg)

<br>

#### `Table-View`
In Table-View-Perspective you can see sphinx-needs data in table. You can select which columns should
be visible and which hidden.

![](https://raw.githubusercontent.com/mi-parkes/sphinx-needs-data-explorer/6d9afc22473bdcf64cf12f92188f1c4203ce3ae5/doc/source/images/table-perspective.jpg)

<br>

#### `File-View`
In File-View-Perspective, you can see a list of files in which Sphinx-needs data were found.

![](https://raw.githubusercontent.com/mi-parkes/sphinx-needs-data-explorer/6d9afc22473bdcf64cf12f92188f1c4203ce3ae5/doc/source/images/file-perspective.jpg)

<br>

### Powerfull Interactive Data Filtering
You can predefine filtering expressions during documentation generation or interactively while browsing documentation, and apply the data filtering across all three view perspectives.

![](https://raw.githubusercontent.com/mi-parkes/sphinx-needs-data-explorer/6d9afc22473bdcf64cf12f92188f1c4203ce3ae5/doc/source/images/data-filtering.jpg)

You can use attribute lookup table while writing your filters.

![](https://raw.githubusercontent.com/mi-parkes/sphinx-needs-data-explorer/6d9afc22473bdcf64cf12f92188f1c4203ce3ae5/doc/source/images/scr6.jpg)

<br>

### Exploring In-Neighbours, Out-Neighbours or both

![](https://raw.githubusercontent.com/mi-parkes/sphinx-needs-data-explorer/6d9afc22473bdcf64cf12f92188f1c4203ce3ae5/doc/source/images/sh2.jpg)

<br>

### Visualizing Constraint Violations in Network Transitions 

![](https://raw.githubusercontent.com/mi-parkes/sphinx-needs-data-explorer/6d9afc22473bdcf64cf12f92188f1c4203ce3ae5/doc/source/images/scr7.jpg)

<br>

### Controlling Neighborhood Depth in Network Visualization

![](https://raw.githubusercontent.com/mi-parkes/sphinx-needs-data-explorer/6d9afc22473bdcf64cf12f92188f1c4203ce3ae5/doc/source/images/depthview.gif)

<br>

### Switching between Perspective Views and Documentation

![](https://raw.githubusercontent.com/mi-parkes/sphinx-needs-data-explorer/6d9afc22473bdcf64cf12f92188f1c4203ce3ae5/doc/source/images/sh3.jpg)

<br>

### Interaction

![](https://raw.githubusercontent.com/mi-parkes/sphinx-needs-data-explorer/6d9afc22473bdcf64cf12f92188f1c4203ce3ae5/doc/source/images/sphinx-needs-data-explorer.gif)

<br>

## Installation

You can install [sphinx-needs-data-explorer](https://pypi.org/project/sphinx-needs-data-explorer/) with pip

    pip install sphinx-needs-data-explorer

Alternatively (Linux)

    git clone https://github.com/mi-parkes/sphinx-needs-data-explorer.git
    cd sphinx-needs-data-explorer

    poetry install
    poetry build
    poetry run task doc

    # you can then install the package in your virtual environment
    pip install dist/sphinx_needs_data_explorer*.whl

## Activation

In your conf.py configuration file, add `sphinx_needs_data_explorer` to your extensions list. And, please, make sure that `sphinx_needs` extension is configured to generate needs.json file in the root of your documentation E.g.:

    extensions = [
      ...
      'sphinx_needs_data_explorer'
      ...
    ]
    ...
    needs_build_json = True

or you can include it only if the extension is available in your virtual environment:

    ...
    try:
        import sphinx-needs-data-explorer
        extensions.add('sphinx-needs-data-explorer')
    except ImportError:
        pass
    ...
    needs_build_json = True

<br>

If your project uses [sphinx_book_theme](https://github.com/executablebooks/sphinx-book-theme),
`sphinx_needs_data_explorer` supports full integration in your documentation by adding `E` header button accesible from any documentation page.

![](https://raw.githubusercontent.com/mi-parkes/sphinx-needs-data-explorer/6d9afc22473bdcf64cf12f92188f1c4203ce3ae5/doc/source/images/E-header-button-doc.jpg)

Otherwise, you can create hyperlink to `sphinx_needs_data_explorer` by adding the following role in your .rst file(s)

    :sphinx_needs_data_explorer:`Sphinx Needs Data Explorer Test`

## Configuration

If defined, the following parameters are used for configuration:

* [needs_extra_options](https://sphinx-needs.readthedocs.io/en/latest/configuration.html#needs-extra-options) - the parameter defines extra sphinx-needs options
* [needs_extra_links](https://sphinx-needs.readthedocs.io/en/latest/configuration.html#needs-extra-links) - the parameter defines the type links to use when extracting sphinx-needs linkage
* [needs_types](https://sphinx-needs.readthedocs.io/en/latest/configuration.html#needs-types) - the parameter defines sphinx-needs types and their attributes like node colors

You can predefine filtering expressions to populate the filter drop-down list:

    sphinx_needs_data_explorer_config = {
        "filters":[
            "status=='open'",
            "['15','16'] in id",
            "title ~ /r.*[0-9]+5'$/i",
            "type != 'req' && incoming==[]",
            "type=='spec' && outgoing!=[] && title ~ /5'$/"
        ]
    }

`sphinx_needs_data_explorer` Help lists all attributes found in your project that can be used for data filtering.

![](https://raw.githubusercontent.com/mi-parkes/sphinx-needs-data-explorer/6d9afc22473bdcf64cf12f92188f1c4203ce3ae5/doc/source/images/help1.jpg)

Visualizing Constraint Violations in Network Transitions:

    sphinx_needs_data_explorer_config = {
        "valid-linkage-color":"Black",
        "invalid-linkage-color":"OrangeRed",
        "valid-linkage":{
            'need': {
                'need':'refinement'
            },
            'feat': {
                'feat':'refinement',
                'need':'links'
            },
            ...
        }
    }


