Raised version to 0.1.19. Added nneds_ir_required option for configur…

…ation. Added changelog for documentation

README.rst

@@ -1,4 +1,4 @@
-Complete documentation: http://sphinxcontrib-needs.readthedocs.io/en/latest/
+*Complete, rendered documentation*: http://sphinxcontrib-needs.readthedocs.io/en/latest/
 
 This package contains the needs Sphinx extension.
 

docs/changelog.rst

@@ -0,0 +1,35 @@
+Changelog
+=========
+
+0.1.19
+------
+
+* Added configuration parameter :ref:`needs_id_required`.
+* Backwards compatibility changes:
+
+ * Reimplemented **needlist** as alias for :ref:`needfilter`
+ * Added *need* directive/need as part of the default :ref:`need_types` configuration.
+
+0.1.18
+------
+
+**Initial start for the changelog**
+
+* Free definable need types (Requirements, Bugs, Tests, Employees, ...)
+* Allowing configuration of needs with a
+
+ * directive name
+ * meaningful title
+ * prefix for generated IDs
+ * color
+
+* Added **needfilter** directive
+* Added layouts for needfilter:
+
+ * list (default)
+ * table
+ * diagram (based on plantuml)
+
+* Integrated interaction with the activated plantuml sphinx extension
+
+* Added role **need** to create a reference to a need by giving the id

docs/index.rst

@@ -233,6 +233,8 @@ You can also use **:hide_status:** and **:hide_tags:** to hide the related infor
     By default the above example works also with `.. spec::`, `.. impl::`, `.. test::` and all other need types,
     which are configured via **needs_types**.
 
+.. _needfilter:
+
 needfilter
 ----------
 
@@ -334,7 +336,9 @@ By default it is set to::
     needs_types = [dict(directive="req", title="Requirement", prefix="R_", color="#BFD8D2", style="node"),
                    dict(directive="spec", title="Specification", prefix="S_", color="#FEDCD2", style="node"),
                    dict(directive="impl", title="Implementation", prefix="I_", color="#DF744A", style="node"),
-                   dict(directive="test", title="Test Case", prefix="T_", color="#DCB239", style="node")
+                   dict(directive="test", title="Test Case", prefix="T_", color="#DCB239", style="node"),
+                   # Kept for backwards compatibility
+                   dict(directive="need", title="Need", prefix="N_", color="#9856a5", style="node")
                ]
 
 needs_types must be a list of dictionaries, where each dictionary **must** contain the following items:
@@ -420,3 +424,38 @@ By default the following template is used:
 
     <size:12>{{type_name}}</size>\\n**{{title}}**\\n<size:10>{{id}}</size>
 
+.. _needs_id_required:
+
+needs_id_required
+~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 0.1.19
+
+Forces the user to set an ID for each need, which gets defined.
+
+So no ID is autogenerated anymore, if this option is set to True::
+
+    needs_id_required = True
+
+By default this option is set to **False**.
+
+If an ID is missing sphinx throws the exception "NeedsNoIdException" and stops the build.
+
+**Example**::
+
+    # With needs_id_required = True
+
+    .. req:: Working Requirement
+       :id: R_001
+
+    .. req:: *Not* working, because :id: is not set.
+
+
+    # With needs_id_required = False
+
+    .. req:: This works now!
+
+
+
+
+.. include:: changelog.rst

setup.py

@@ -8,7 +8,7 @@
 
 setup(
     name='sphinxcontrib-needs',
-    version='0.1.18',
+    version='0.1.19',
     url='http://github.com/useblocks/sphinxcontrib-needs',
     download_url='http://pypi.python.org/pypi/sphinxcontrib-needs',
     license='BSD',

sphinxcontrib/needs.py

@@ -7,6 +7,7 @@
 from sphinx.roles import XRefRole
 from sphinx.environment import NoUri
 from sphinx.util.nodes import make_refnode
+from sphinx.errors import SphinxError
 
 DEFAULT_TEMPLATE = """
 .. _{{id}}:
@@ -41,7 +42,9 @@ def setup(app):
                          [dict(directive="req", title="Requirement", prefix="R_", color="#BFD8D2", style="node"),
                           dict(directive="spec", title="Specification", prefix="S_", color="#FEDCD2", style="node"),
                           dict(directive="impl", title="Implementation", prefix="I_", color="#DF744A", style="node"),
-                          dict(directive="test", title="Test Case", prefix="T_", color="#DCB239", style="node")
+                          dict(directive="test", title="Test Case", prefix="T_", color="#DCB239", style="node"),
+                          # Kept for backwards compatibility
+                          dict(directive="need", title="Need", prefix="N_", color="#9856a5", style="node")
                           ],
                          'html')
     app.add_config_value('needs_template',
@@ -55,6 +58,7 @@ def setup(app):
     app.add_config_value('needs_id_prefix_specs', "", 'html')
     app.add_config_value('needs_id_length', 5, 'html')
     app.add_config_value('needs_specs_show_needlist', False, 'html')
+    app.add_config_value('needs_id_required', False, 'html')
 
     app.add_config_value('needs_diagram_template',
                          DEFAULT_DIAGRAM_TEMPLATE,
@@ -78,9 +82,11 @@ def setup(app):
                                   innernodeclass=nodes.emphasis,
                                   warn_dangling=True))
 
-    # app.add_directive('need', NeedDirective)
     app.add_directive('needfilter', NeedfilterDirective)
 
+    # Kept for backwards compatibility
+    app.add_directive('needlist', NeedfilterDirective)
+
     # Make connections to events
     app.connect('env-purge-doc', purge_needs)
     app.connect('doctree-resolved', process_need_nodes)
@@ -151,6 +157,10 @@ def run(self):
         # TODO: Check, if id was already given. If True, recalculate id
         # id = self.options.get("id", ''.join(random.SystemRandom().choice(string.ascii_uppercase + string.digits) for
         #  _ in range(5)))
+        if "id" not in self.options.keys() and env.app.config.needs_id_required:
+            raise NeedsNoIdException("An id is missing for this need and must be set, because 'needs_id_required' "
+                                "is set to True in conf.py")
+
         id = self.options.get("id",
                               "%s%s" % (type_prefix,
                                         hashlib.sha1(self.arguments[0].encode("UTF-8")).hexdigest().upper()
@@ -598,4 +608,8 @@ def rstjinja(app, docname, source):
     rendered = app.builder.templates.render_string(
         src, app.config.html_context
     )
-    source[0] = rendered
+    source[0] = rendered
+
+
+class NeedsNoIdException(SphinxError):
+    pass

tests/test_needs.py

@@ -1,5 +1,6 @@
 from sphinx_testing import with_app
-
+from nose.tools import raises
+from sphinxcontrib.needs import NeedsNoIdException
 
 @with_app(buildername='html', srcdir='../docs')
 def test_build_html(app, status, warning):
@@ -23,4 +24,11 @@ def test_build_epub(app, status, warning):
 
 @with_app(buildername='json', srcdir='../docs')
 def test_build_json(app, status, warning):
-    app.builder.build_all()
+    app.builder.build_all()
+
+
+# Test with needs_id_required=True and missing ids in docs.
+@raises(NeedsNoIdException)
+@with_app(buildername='html', srcdir='../docs', confoverrides={"needs_id_required": True})
+def test__id_required_build_html(app, status, warning):
+    app.builder.build_all()