Initial dev-prototype for #137

Author: danwos

docs/changelog.rst

@@ -6,6 +6,14 @@ License
 
 .. include:: ../LICENSE
 
+0.7.0
+-----
+:Released: under development
+
+* Improvement: Providing :ref:`needs_external_needs` to allow usage and referencing of external needs.
+  (`#137 <https://github.com/useblocks/sphinxcontrib-needs/issues/137>`_)
+* Bugfix: :ref:`needtable` shows attributes with value ``False`` again.
+
 0.6.3
 -----
 :Released: under development
@@ -16,7 +24,7 @@ License
   (`#263 <https://github.com/useblocks/sphinxcontrib-needs/issues/263>`_)
 * Bugfix: CSS fix for needtable :ref:`needtable_style_row`.
   (`#195 <https://github.com/useblocks/sphinxcontrib-needs/issues/195>`_)
-* Bugfix: ``current_need` var is accessible in all need-filters.
+* Bugfix: ``current_need`` var is accessible in all need-filters.
   (`#169 <https://github.com/useblocks/sphinxcontrib-needs/issues/169>`_)
 * Bugfix: Sets defaults for color and style of need type configuration, if not set by user.
   (`#151 <https://github.com/useblocks/sphinxcontrib-needs/issues/151>`_)

docs/configuration.rst

@@ -1101,6 +1101,49 @@ Default: ``False``.
 
     needs_service_all_data = True
 
+
+.. _needs_external_needs:
+
+needs_external_needs
+~~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 0.7.0
+
+Allows to reference and use external needs without having their representation in your own documentation.
+(Unlike :ref:`needimport`, which creates need-objects from a local ``needs.json`` only).
+
+.. code-block:: python
+
+    needs_external_needs = [
+      {
+        'base_url': 'http://mydocs/my_project',
+        'json_url':  'http://mydocs/my_project/needs.json',
+        'version': '1.0',
+        'id_prefix': 'ext_',
+        'css_class': 'external_link',
+      },
+      {
+        'base_url': 'http://mydocs/another_project/',
+        'json_url':  'http://mydocs/another_project/data/exports/needs.json',
+        'version': '2.5',
+        'id_prefix': 'other_',
+        'css_class': 'project_x',
+      }
+    ]
+
+``needs_external_needs`` must be a list of dictionary elements and each dictionary must/can have the following
+keys:
+
+:base_url: Base url which is used to calculate the final, specific need url. Normally the path under which the ``index.html`` is provided.
+:json_url: url, which can be used to download the ``needs.json`` (or similar) file.
+:version: Defines the version to use inside the ``needs.json`` file (*optional*).
+:id_prefix: Prefix as string, which will be added to all id of external needs. Needed, if there is the risk that
+            needs from different projects may have the same id (*optional*).
+:css_class: A class name as string, which gets set in link representations like :ref:`needtable`.
+            The related css class definition must be done by the user, e.g. by :ref:`own_css`.
+            (*optional*) (*default*: ``external_link``)
+
+
 Removed options
 ---------------
 

docs/layout_styles.rst

@@ -528,6 +528,8 @@ Sphinx-needs provides the following css styles:
 
 .. image:: _static/need_dark.png
 
+.. _own_css:
+
 Own CSS file on sphinx level
 ++++++++++++++++++++++++++++
 

poetry.lock

@@ -39,6 +39,8 @@ sphinx = [
     { version = ">2.2, <=3.0", python = "~3.6" },
     { version = ">2.2, <=4.0", python = "^3.7" },
 ]
+requests-file = "^1.5.1"
+requests = "^2.25.1"
 
 [tool.poetry.dev-dependencies]
 
@@ -64,9 +66,9 @@ line-length = 120
 [tool.isort]
 profile = "black"
 
+[tool.poetry.extras]
+docs = ["sphinx"]
 [build-system]
 requires = ["poetry-core>=1.0.0"]
 build-backend = "poetry.core.masonry.api"
 
-[tool.poetry.extras]
-docs = ["sphinx"]

pyproject.toml

@@ -6,4 +6,4 @@
     add_need_type,
     get_need_types,
 )
-from .need import add_need, make_hashed_id
+from .need import add_external_need, add_need, make_hashed_id