Builders

needs

New 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 needs and a file called needs.json inside a given build-folder.

Usage

sphinx-build -b needs source_dir build_dir

History data

The builder stores the needs under a version, which is 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 nice history data.

Exporting filters

New in version 0.3.11.

The results and filter configuration of a filter based directive, like needlist, needtable or needflow, get exported, if the option export_id is used in the related directive.

This allows to export specified filter results only.

Example:

.. needtable::
   :status: open
   :filter: "test" in tags
   :export_id: filter_01

Format

{
"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",
        "filters": {
           "FILTER_1": {
             "amount": 1,
             "export_id": "FILTER_1",
             "filter": "",
             "result": [
                 "IMPL_01",
             ],
             "status": [],
             "tags": "",
             "types": []
        },
        "needs": {
            "IMPL_01": {
                "description": "Incoming links of this spec: :need_incoming:`IMPL_01`.",
                "id": "IMPL_01",
                "links": [
                    "OWN_ID_123"
                ],
                "sections": [
                    "Examples"
                ],
                "status": null,
                "tags": [],
                "title": "Implementation for specification",
                "type": "impl",
                "type_name": "Implementation"
            }
        }
    },
    "1.5": {
        "created": "2017-07-03T16:10:31.633425",
        "filters": {
           "FILTER_1": {
             "amount": 1,
             "export_id": "FILTER_1",
             "filter": "",
             "result": [
                 "IMPL_01",
             ],
             "status": [],
             "tags": "",
             "types": []
        },
        "needs": {
            "IMPL_01": {
                "description": "Incoming links",
                "id": "IMPL_01",
                "links": [
                    "OWN_ID_123"
                ],
                "sections": [
                    "Examples"
                ],
                "status": "closed",
                "tags": ["links","update"],
                "title": "Implementation for specification",
                "type": "impl",
                "type_name": "Implementation"
            }
        }
    }
}