Skip to content
Back to top
View this page
Edit this page

# Builders

## needs

Added in version 0.1.30.

The needs builder exports all found needs and selected filter results to a single json file.

The build creates a folder called needs and a file called needs.json inside the given build-folder.

### Usage

    sphinx-build -b needs source_dir build_dir

Hint

As an alternative, you can set the needs_build_json parameter in conf.py to create a `needs.json` file directly during the build of another output format like `html`.

### History data

The builder stores the needs under a version taken from your conf.py.

If a needs.json is imported (see needs_file) and you raise the documentation version, the new version is stored beside the old version(s) inside the needs.json.

Hint

If you generate and store/archive (e.g. in git) the needs.json file every time you raise your documentation version, you will get a nice history data.

### Format

As well as the `filters` and `needs` data, the needs.json file also contains the `needs_schema`. This is a JSON schema of for the data structure of a single need, and also includes a `field_type` for each field, to denote the source of the field, that can be one of: `core`, `links`, `backlinks`, `extra`, `global`.

See also needs_json_exclude_fields, needs_json_remove_defaults, and needs_reproducible_json for more options on modifying the content of the `needs.json` file.

Note

`needs_defaults_removed` is a flag that is set to `true` if the defaults are removed from the needs. If it is missing or set to `false`, the defaults are not removed.

    {
    "created": "2017-07-03T11:54:42.433876",
    "current_version": "1.5",
    "project": "needs test docs",
    "versions": {
        "1.0": {
            "created": "2017-07-03T11:54:42.433868",
            "needs_schema": {
                "$schema": "http://json-schema.org/draft-07/schema#",
                "properties": {
                    "id": {
                        "description": "ID of the data.",
                        "field_type": "core",
                        "type": "string"
                    },
                    "type": {
                        "description": "Type of the need.",
                        "field_type": "core",
                        "type": "string"
                    },
                    "links": {
                        "description": "Link field",
                        "field_type": "links",
                        "items": {
                            "type": "string"
                        },
                        "type": "array",
                        "default": []
                    },
                    "status": {
                        "description": "Status of the need.",
                        "field_type": "core",
                        "type": [
                            "string",
                            "null"
                        ],
                        "default": null
                    },
                    ...
                }
            },
            "needs_defaults_removed": true,
            "needs": {
                "IMPL_01": {
                    "id": "IMPL_01",
                    "type": "impl",
                    "links": ["OWN_ID_123"],
                    ...
                },
                ...
            }
        },
        "1.5": {
            "created": "2017-07-03T16:10:31.633425",
            "needs_schema": {
                "id": {
                    "description": "ID of the data.",
                    "field_type": "core",
                    "type": "string"
                },
                "type": {
                    "description": "Type of the need.",
                    "field_type": "core",
                    "type": "string"
                },
                "links": {
                    "description": "Link field",
                    "field_type": "links",
                    "items": {
                        "type": "string"
                    },
                    "type": "array",
                    "default": []
                },
                "status": {
                    "description": "Status of the need.",
                    "field_type": "core",
                    "type": [
                        "string",
                        "null"
                    ],
                    "default": null
                },
                ...
            },
            "needs_defaults_removed": true,
            "needs": {
                "IMPL_01": {
                    "id": "IMPL_01",
                    "type": "impl",
                    "links": ["OWN_ID_123"],
                    "status": "closed",
                    ...
                },
                ...
            }
        }
    }

## needumls

The needumls builder saves each needuml generated plantuml code to a file, and stores all the files into a single folder during the build. The file is created only if the option `:save:` from needuml is configured.

The build creates a folder called needumls inside the given build-folder, e.g. _build/needumls.

### Usage

    make needumls

or

    sphinx-build -M needumls source_dir build_dir

Hint

As an alternative, you can set the config option needs_build_needumls to export the needumls files during each build.

## needs_id

Added in version 2.0.0.

The needs_id builder exports all found needs and selected filter results to a set json files of each need with the name is `id` of need.

The build creates a folder called :ref:`needs_build_json_per_id_path` and all file json of each need inside the given build-folder.

### Usage

    sphinx-build -b needs_id source_dir build_dir