Skip to content

Commit

Permalink
Added builder *needs* to exports needs into a single json file
Browse files Browse the repository at this point in the history
  • Loading branch information
@danwos
danwos committed Jul 3, 2017
1 parent f2066da commit 0a96333
Show file tree
Hide file tree
Showing 10 changed files with 397 additions and 13 deletions.
81 changes: 81 additions & 0 deletions docs/builders.rst
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,81 @@
.. _builders:

Builders
========

.. _needs_builder:

needs
-----
.. versionadded:: 0.1.30

The **needs** builder exports all found needs to a single json file.

By default, the used file is called **needs.json** and is stored beside your conf.py file.
This can be changed by setting :ref:`needs_file`.

Usage
+++++

.. code-block:: bash
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** already exists 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.

Format
++++++

.. code-block:: python
{
"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": {
"IMPL_01": {
"description": "Incoming links of this spec: :need_incoming:`IMPL_01`.",
"id": "IMPL_01",
"links": [
"OWN_ID_123"
],
"status": null,
"tags": [],
"title": "Implementation for specification",
"type": "impl",
"type_name": "Implementation"
}
}
}
"1.5": {
"created": "2017-07-03T16:10:31.633425",
"needs": {
"IMPL_01": {
"description": "Incoming links",
"id": "IMPL_01",
"links": [
"OWN_ID_123"
],
"status": "closed",
"tags": ["links","update"],
"title": "Implementation for specification",
"type": "impl",
"type_name": "Implementation"
}
}
}
}
4 changes: 4 additions & 0 deletions docs/changelog.rst
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,10 @@
Changelog
=========

0.1.30
------
* Improvement: Builder :ref:`needs_builder` added, which exports all needs to a json file.

0.1.29
------

Expand Down
18 changes: 9 additions & 9 deletions docs/conf.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,15 @@
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.

# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = '1.30'
# The full version, including alpha/beta/rc tags.
release = '1.30'

on_rtd = os.environ.get('READTHEDOCS') == 'True'
if on_rtd:
extensions = ['sphinxcontrib.needs']
Expand Down Expand Up @@ -129,15 +138,6 @@
copyright = '2017, team useblocks'
author = 'team useblocks'

# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = '1.0'
# The full version, including alpha/beta/rc tags.
release = '1.0'

# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#
Expand Down
11 changes: 10 additions & 1 deletion docs/configuration.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -193,4 +193,13 @@ Can be combined with **needs_show_link_type**.

Activate it by setting it on True in your conf.py::

needs_show_link_title = True
needs_show_link_title = True

.. _needs_file:

needs_file
~~~~~~~~~~
.. versionadded:: 0.1.30

Defines the location of a json file, which is used by the builder :ref:`needs_builder`.
Default value: *needs.json*.
1 change: 1 addition & 0 deletions docs/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -115,6 +115,7 @@ Content
directives
roles
configuration
builders
examples
changelog

Expand Down
182 changes: 182 additions & 0 deletions docs/needs.json
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,182 @@
{
"created": "2017-07-03T11:54:42.433876",
"current_version": "1.0",
"project": "needs test docs",
"versions": {
"1.0": {
"created": "2017-07-03T11:54:42.433868",
"needs": {
"IMPL_01": {
"description": "Incoming links of this spec: :need_incoming:`IMPL_01`.",
"id": "IMPL_01",
"links": [
"OWN_ID_123"
],
"status": null,
"tags": [],
"title": "Implementation for specification",
"type": "impl",
"type_name": "Implementation"
},
"OWN_ID_123": {
"description": "Outgoing links of this spec: :need_outgoing:`OWN_ID_123`.",
"id": "OWN_ID_123",
"links": [
"R_F4722"
],
"status": null,
"tags": [],
"title": "Specification of a requirement",
"type": "spec",
"type_name": "Specification"
},
"REQ_001": {
"description": "This is an awesome requirement and it includes a nice title,\na given id, a tag and this text as description.",
"id": "REQ_001",
"links": [],
"status": null,
"tags": [
"example"
],
"title": "My first requirement",
"type": "req",
"type_name": "Requirement"
},
"ROLES_REQ_1": {
"description": "",
"id": "ROLES_REQ_1",
"links": [],
"status": null,
"tags": [],
"title": "Sliced Bread",
"type": "req",
"type_name": "Requirement"
},
"ROLES_REQ_2": {
"description": "",
"id": "ROLES_REQ_2",
"links": [
"ROLES_REQ_1"
],
"status": null,
"tags": [],
"title": "Butter on Bread",
"type": "req",
"type_name": "Requirement"
},
"R_22EB2": {
"description": "",
"id": "R_22EB2",
"links": [],
"status": "closed",
"tags": [
"B",
"filter"
],
"title": "Requirement B",
"type": "req",
"type_name": "Requirement"
},
"R_2A9D0": {
"description": "",
"id": "R_2A9D0",
"links": [],
"status": "open",
"tags": [
"A",
"filter"
],
"title": "Requirement A",
"type": "req",
"type_name": "Requirement"
},
"R_F4722": {
"description": "This is my **first** requirement!!\n\n.. note:: You can use any rst code inside it :)",
"id": "R_F4722",
"links": [],
"status": "open",
"tags": [
"requirement",
"test",
"awesome"
],
"title": "My first requirement",
"type": "req",
"type_name": "Requirement"
},
"S_01A67": {
"description": "",
"id": "S_01A67",
"links": [],
"status": "open",
"tags": [
"B",
"filter"
],
"title": "Specification B",
"type": "spec",
"type_name": "Specification"
},
"S_503A1": {
"description": "We haven't set an **ID** here, so sphinxcontrib-needs\nwill generated one for us.\n\nBut we have **set a link** to our first requirement and\nalso a *status* is given.",
"id": "S_503A1",
"links": [
"REQ_001"
],
"status": "done",
"tags": [
"important",
"example"
],
"title": "Spec for a requirement",
"type": "spec",
"type_name": "Specification"
},
"S_D70B0": {
"description": "",
"id": "S_D70B0",
"links": [],
"status": "closed",
"tags": [
"A",
"filter"
],
"title": "Specification A",
"type": "spec",
"type_name": "Specification"
},
"T_5CCAA": {
"description": "",
"id": "T_5CCAA",
"links": [],
"status": null,
"tags": [
"awesome",
"filter"
],
"title": "Test 1",
"type": "test",
"type_name": "Test Case"
},
"T_C3893": {
"description": "This test checks :need:`impl_01` for :need:`OWN_ID_123` inside a\nPython 2.7 environment.",
"id": "T_C3893",
"links": [
"OWN_ID_123",
"IMPL_01"
],
"status": "implemented",
"tags": [
"test",
"user_interface",
"python27"
],
"title": "Test for XY",
"type": "test",
"type_name": "Test Case"
}
},
"needs_amount": 13
}
}
}
2 changes: 1 addition & 1 deletion setup.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@

setup(
name='sphinxcontrib-needs',
version='0.1.29',
version='0.1.30',
url='http://github.com/useblocks/sphinxcontrib-needs',
download_url='http://pypi.python.org/pypi/sphinxcontrib-needs',
license='BSD',
Expand Down
38 changes: 38 additions & 0 deletions sphinxcontrib/builder.py
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
from sphinxcontrib.utils import NeedsList
from sphinx.builders.text import TextBuilder
from sphinx.util import logging
# import logging


class NeedsBuilder(TextBuilder):
name = 'needs'
format = 'json'
file_suffix = '.txt'
links_suffix = None

def init(self):
pass

def write_doc(self, docname, doctree):
pass

def finish(self):
log = logging.getLogger(__name__)
needs = self.env.need_all_needs
config = self.env.config
version = config.version
needs_list = NeedsList(config)

needs_list.load_json()

for key, need in needs.items():
needs_list.add_need(version, need["title"], need["id"], need["type"], need["type_name"],
need["content"], need["status"], need["tags"], need["links"])
try:
needs_list.write_json()
except Exception as e:
log.error("Error during writing json file: {0}".format(e))
else:
log.info("Needs successfully exported")


Loading

0 comments on commit 0a96333

Please sign in to comment.