Changelog¶
5.1.0¶
- Released:
06.03.2025
- Full Changelog:
The needs_global_options configuration option has been updated to a new format, to be more explicit and to allow for future improvements PR #1413. The old format is currently still supported, but will emit a warning. Additionally, checks are put in place to ensure that the keys used are from the allowed set (PR #1410).:
any
needs_extra_options
fieldany
needs_extra_links
fieldstatus
layout
style
tags
constraints
needs_global_options = {
"field1": "a",
"field2": ("a", 'status == "done"'),
"field3": ("a", 'status == "done"', "b"),
"field4": [
("a", 'status == "done"'),
("b", 'status == "ongoing"'),
("c", 'status == "other"', "d"),
],
}
needs_global_options = {
"field1": {"default": "a"},
"field2": {"predicates": [('status == "done"', "a")]},
"field3": {
"predicates": [('status == "done"', "a")],
"default": "b",
},
"field4": {
"predicates": [
('status == "done"', "a"),
('status == "ongoing"', "b"),
('status == "other"', "c"),
],
"default": "d",
},
}
5.0.0¶
- Released:
18.02.2025
- Full Changelog:
This release includes a number of changes, to bring more clarity to the needs data structure and post-processing steps. In most cases it should not be breaking, but may be in some corner cases.
✨ Add
c.this_doc()
check for use in directive:filter:
option PR #1393 and PR #1405This allows for filtering of needs only in the same document as the directive itself, e.g.
.. needextend:: c.this_doc() and status is None :status: open
This works for all common filtered directives, see Filtering for needs on the current page
♻️ Remove
full_title
need field and only trim generated titles PR #1407The existence of both
title
andfull_title
is confusing and unnecessary (in most cases these are equal), and sofull_title
is removed.Trimming (when needs_max_title_length is set) is now only applied to auto-generated titles, as per the documentation in needs_title_from_content
♻️ Make
needextend
argument declarative PR #1391The argument for
needextend
can refer to either a single need ID or filter function. Currently, the format cannot be known until all needs have been processed, and it is resolved during post-processing. This is problematic for (a) user readability, (b) improving processing performance and issue feedbackThis PR slightly modifies the argument processing to allow for two “explicit” formats:
<ID>
, if the argument is enclosed in<>
it is always processed as a single ID"filter string"
, if the argument is enclosed in""
it is always processed as a filter string
See needextend for more information.
♻️ Remove back link manipulation from
needextend
PR #1386Back links are computed at the end of the need post-processing, after
needextend
have been applied.Back links should always be in-sync with forward links, therefore it doesn’t make sense to modify back links in this way.
♻️ Do not process dynamic functions on internal need fields PR #1387 and PR #1406
For most “internal” need fields it does not make sense that these would be dynamic, and anyway this would fail since their values are not string types.
Dynamic function processing is now skipped, for core fields that should not be altered by the user. The following fields are allowed to contain dynamic functions:
status
tags
style
constraints
all
needs_extra_options
all
needs_extra_links
all
needs_global_options
♻️ Remove
delete
from internal needs andneeds.json
PR #1347The
:delete:
option on a need directive deletes a need before creating/storing it, therefore it is impossible for it to be anything other thanFalse
. Storing the field on a need is misleading, because it suggests that the need will be deleted, which is not possible with the current sphinx-needs logic.👌 Add type warnings of extra options in external/import reads PR #1389
Currently, the value of all extra options is expected to be a string; other types are not supported in various aspects of sphinx-needs (such as
needextend
, dynamic functions and filtering), and in-fact are already silently converted to strings during the reads.The warnings
needs.mistyped_external_values
andneeds.mistyped_import_values
are added for non-string values, forneeds_external_needs
andneedimport
sources respectively.🔧 Synchronize list splitting behaviour in
need
andneedextend
directives PR #1385
4.2.0¶
- Released:
07.01.2025
- Full Changelog:
⬆️ Drop Python 3.8 and Sphinx 6
✨ Add needs_import_keys configuration PR #1379
👌 Allow
filter-func
inneedpie
to have multiple dots in the import path PR #1350🐛 Make external paths relative to
confdir
, notsrcdir
PR #1378🔧 Release needs data mutation lock at end of process PR #1359
🔧 Add
lineno
to default output ofneeds.json
PR #1346
4.1.0¶
- Released:
28.10.2024
- Full Changelog:
New¶
✨ Add needs_from_toml configuration PR #1337
Configuration can now be loaded from a TOML file, using the needs_from_toml configuration option. See needs_from_toml for more information.
✨ Allow configuring description of extra options in
needs_extra_options
PR #1338The
needs_extra_options
configuration option now supports dict items with aname
anddescription
key, See needs_extra_options for more information.
Fixes¶
🐛 Fix clickable links to needs in
needflow
, when using thegraphviz
engine PR #1339🐛 Allow sphinx-needs to run without
sphinxcontrib.plantuml
installed PR #1328🔧 Remove some internal fields from needs layout PR #1330
🔧 Merge defaults into user-defined configuration earlier (to avoid sphinx warnings) PR #1341
4.0.0¶
- Released:
09.10.2024
- Full Changelog:
Breaking Changes¶
This commit contains a number of breaking changes:
Improvements to filtering at scale¶
For large projects, the filtering of needs in analytical directives such as needtable, needuml, etc, can be slow due to
requiring an O(N)
scan of all needs to determine which to include.
To address this, the storage of needs has been refactored to allow for pre-indexing of common need keys, such as id
, status
, tags
, etc, after the read/collection phase.
Filter strings such as id == "my_id"
are then pre-processed to take advantage of these indexes and allow for O(1)
filtering of needs, see the Filter string performance section for more information.
This change has required changes to the internal API and stricter control on the access to and modification of need data, which may affect custom extensions that modified needs data directly:
Access to internal data from the Sphinx env object has been made private
Needs data during the write phase is exposed with either the read-only
NeedsView
orNeedsAndPartsListView
, depending on the context.Access to needs data, during the write phase, can now be achieved via
get_needs_view()
Access to mutable needs should generally be avoided outside of the formal means, but for back-compatibility the following Sphinx event callbacks are now available:
needs-before-post-processing
: callbacksfunc(app, needs)
are called just before the needs are post-processed (e.g. processing dynamic functions and back links)needs-before-sealing
: callbacksfunc(app, needs)
just after post-processing, and before the needs are changed to read-only
Additionally, to identify any long running filters, the needs_uml_process_max_time, needs_filter_max_time and needs_debug_filters configuration options have been added.
Key changes were made in:
♻️ Replace need dicts/lists with views (with fast filtering) in PR #1281
🔧 split
filter_needs
func by needs type in PR #1276🔧 Make direct access to
env
attributes private in PR #1310👌 Move sorting to end of
process_filters
in PR #1257🔧 Improve
process_filters
function in PR #1256🔧 Improve internal API for needs access in PR #1255
👌 Add
needs_uml_process_max_time
configuration in PR #1314♻️ Add
needs_filter_max_time
/needs_debug_filters
, deprecateexport_id
in PR #1309
Improved warnings¶
sphinx-needs is designed to be durable and only except when absolutely necessary. Any non-fatal issues during the build are logged as Sphinx warnings. The warnings types have been improved and stabilised to provide more information and context, see Build Warnings for more information.
Additionally, the add_need()
function will now only raise the singular exception InvalidNeedException
for all need creation issues.
Key changes were made in:
Improved needs.json
¶
A number of output need fields have been changed, to simplify the output. Key changes were made in:
Replacement of [[...]]
and need_func
in need content¶
The parsing of the [[...]]
dynamic function syntax in need content could cause confusion and unexpected behaviour.
This has been deprecated in favour of the new, more explicit ndf role, which also deprecates the need_func
role.
Removed deprecation¶
The deprecated needfilter
directive is now removed (PR #1308)
New and improved features¶
✨ add
tags
option forlist2need
directive in PR #1296✨ Add
ids
option forneedimport
in PR #1292👌 Allow
ref
inneeduml
to handle need parts in PR #1222👌 Improve parsing of need option lists with dynamic functions in PR #1272
👌 Improve warning for needextract incompatibility with external needs in PR #1325
🔧 Set
env_version
for sphinx extension in PR #1313
Bug Fixes¶
🐛 Fix removal of
Needextend
nodes in PR #1298🐛 Fix
usage
numbers inneedreport
in PR #1285🐛 Fix
parent_need
propagation from external/imported needs in PR #1286🐛 Fix
need_part
with multi-line content in PR #1284🐛 Fix dynamic functions in
needextract
need in PR #1273🐛 Disallow dynamic functions
[[..]]
in literal content in PR #1263🐛 fix parts defined in nested needs in PR #1265
🐛 Handle malformed
filter-func
option value in PR #1254🐛 Pass
needs
tohighlight
filter ofgraphviz
needflow in PR #1274🐛 Fix parts title for
needflow
withgraphviz
engine in PR #1280🐛 Fix
need_count
division by 0 in PR #1324
3.0.0¶
- Released:
28.08.2024
- Full Changelog:
This release includes a number of new features and improvements, as well as some bug fixes.
Updated dependencies¶
sphinx:
>=5.0,<8
to>=6.0,<9
requests:
^2.25.1
to^2.32
requests-file:
^1.5.1
to^2.1
sphinx-data-viewer:
^0.1.1
to^0.1.5
Documentation and CSS styling¶
The documentation theme has been completely updated, and a tutorial added.
To improve sphinx-needs
compatibility across different Sphinx HTML themes,
the CSS for needs etc has been modified substantially, and so,
if you have custom CSS for your needs, you may need to update it.
See HTML Theme support for more information on how to setup CSS for different themes, and PR #1178, PR #1181, PR #1182 and PR #1184 for the changes.
needflow
improvements¶
The use of Graphviz as the underlying engine for needflow diagrams, in addition to the default PlantUML, is now allowed via the global needs_flow_engine configuration option, or the per-diagram engine option.
The intention being to simplify and improve performance of graph builds, since plantuml
has issues with JVM initialisation times and reliance on a third-party sphinx extension.
See needflow for more information, and PR #1235 for the changes.
additional improvements:
needs.json
improvements¶
A needs_schema
is now included in the needs.json
file (per version), which is a JSON schema for the data structure of a single need.
This includes defaults for each field, and can be used in combination with the needs_json_remove_defaults configuration option to remove these defaults from each individual need.
Together with the new automatic minifying of the needs.json
file, this can reduce the file size by down to 1/8th of its previous size.
The needs_json_exclude_fields configuration option can also be used to modify the excluded need fields from the needs.json
file,
and backlinks are now included in the needs.json
file by default.
See Format for more information, and PR #1230, PR #1232, PR #1233 for the changes.
Additionally, the content_node
, content_id
fields are removed from the internal need data structure (see PR #1241 and PR #1242).
Additional improvements¶
👌 Capture filter processing times when using
needs_debug_measurement=True
in PR #1240👌 Allow
style
andcolor
fields to be omitted forneeds_types
items and a default used in PR #1185👌 Allow
collapse
/delete
/jinja_content
directive options to be flags in PR #1188👌 Improve
need-extend
; allow dynamic functions in lists in PR #1076👌 Add collapse button to
clean_xxx
layouts in PR #1187🐛 fix warnings for duplicate needs in parallel builds in PR #1223
🐛 Fix rendering of
needextract
needs and use warnings instead of exceptions in PR #1243 and PR #1249
2.1.0¶
- Released:
08.05.2024
- Full Changelog:
Improvements¶
👌 Default to warning for missing
needextend
ID in PR #1066👌 Make
needtable
titles more permissive in PR #1102👌 Add
filter_warning
directive option, to replace default warning text in PR #1093👌 Improve and test github
needservice
directive in PR #1113👌 Improve warnings for invalid filters (add source location and subtype) in PR #1128
👌 Exclude external needs from
needs_id_regex
check in PR #1108👌 Fail and emit warning on filters that do not return a boolean result in PR #964
👌 Improve
Need
node creation and content parsing in PR #1168👌 Add loading message to
permalink.html
in PR #1081👌 Remove hard-coding of
completion
andduration
need fields in PR #1127
Bug fixes¶
Internal improvements¶
🔧 Use future annotations in all modules in PR #1111
🔧 Replace black/isort/pyupgrade/flake8 with ruff in PR #1080
🔧 Add better typing for
extra_links
config variable in PR #1131🔧 Centralise need parts creation and strongly type needs in PR #1129
🔧 Fix typing of need docname/lineno in PR #1134
🔧 Type
ExternalSource
config dict in PR #1115🔧 Enforce type checking in
needuml.py
in PR #1116🔧 Enforce type checking in
api/need.py
in PR #1117🔧 Add better typing for
global_options
config variable in PR #1120🔧 Move dead link need fields to internals in PR #1119
🔧 Remove usage of
hide_status
andhide_tags
in PR #1130🔧 Remove
hidden
field fromextra_options
in PR #1124🔧 Remove
constraints
fromextra_options
in PR #1123🔧 Remove use of deprecated
needs_extra_options
asdict
in PR #1126
2.0.0¶
- Released:
13.11.2023
- Full Changelog:
This release is focussed on improving the internal code-base and its build time performance, as well as improved build warnings and other functionality improvements / fixes.
Changed¶
Add Sphinx 7 support and drop Python 3.7 (PR #1056). Sphinx 5, 6, 7 and Python 3.8 to 3.11 are now fully supported and tested.
The
matplotlib
dependency (forneedbar
andneedpie
plots) is now optional, and should be installed withsphinx-needs[plotting]
, see Installation (PR #1061)The
NeedsBuilder
format name is changed toneeds
(PR #978)
New¶
Added Builder needs_id and config option needs_build_json_per_id in
conf.py
(PR #960)Added
needs_reproducible_json
config option for the needs builder, see needs_build_json (PR #1065)Added error messages for constraint failures (PR #1036)
Improved¶
Performance:
General performance improvement (up to 50%) and less memory consumption (~40%).
external_needs
now uses cached templates to save generation time.Improved performance for needextend with single needs.
Improved performance by memoizing the inline parse in
build_need
(PR #968)Remove
deepcopy
of needs data (PR #1033)Optimize
needextend
filter_needs usage (PR #1030)Improve performance of needs builders by skipping document post-transforms (PR #1054)
Other:
Improve sphinx warnings (PR #975, PR #982) All warnings are now suffixed with
[needs]
, and can be suppressed (see suppress_warnings)Improve logging for static file copies (PR #992)
Improve removal of hidden need nodes (PR #1013)
Improve
process_constraints
function (PR #1015)Allow
needextend
directive to use dynamic functions (PR #1052)Remove some unnecessary keys from output
needs.json
(PR #1053)
Fixed¶
Fix gantt chart rendering (PR #984)
Fix
execute_func
(PR #994)Fix adding sections to hidden needs (PR #995)
Fix
NeedImport
logic (PR #1006)Fix creation of need title nodes (PR #1008)
Fix logic for
process_needextend
function (PR #1037)Fix usage of reST syntax in prefix parameter of meta (PR #1046)
Internal¶
🔧 Centralise access to sphinx-needs config to
NeedsSphinxConfig
(PR #998)🔧 Centralise sphinx
env
data access toSphinxNeedsData
(PR #987)🔧 Consolidate needs data post-processing into
post_process_needs_data
function (PR #1039)🔧 Replace
Directive
withSphinxDirective
(PR #986)🔧 Remove
unwrap
function (PR #1017)🔧 Add
remove_node_from_tree
utility function (PR #1063)♻️ Refactor needs post-processing function signatures (PR #1040)
📚 Simplify Sphinx-Needs docs builds (PR #972)
📚 Always use headless plantuml (PR #983)
📚 Add intersphinx (PR #991)
📚 Add outline of extension logic (PR #1012)
📚 Fixed extra links example (PR #1016)
🧪 Remove boilerplate from test build
conf.py
files (PR #989, PR #990)🧪 Add headless java to test builds (PR #988)
🧪 Make documentation builds fail on warnings (PR #1005)
🧪 Add testing of JS scripts using Cypress integrated into PyTest (PR #1051)
🧪 Add code coverage to CI testing (PR #1067)
1.3.0¶
Released: 16.08.2023
Improvement: Configuration option needs_debug_measurement added, which creates a runtime report for debugging purposes. (PR #917)
Bugfix: Replace hardcoded index with config value root_doc. (PR #877)
Bugfix: Fix unbounded memory usage in pickle environment. (PR #912)
Bugfix: Supports “None” body in Github services. (issue #903)
Removed esbonio for VS Code Extension.
Removed configuration option needs_ide_snippets_id to support custom need ID for VS Code Extension snippets.
Removed configuration needs_ide_directive_snippets to support custom directive snippets for IDE features.
Provided new IDE support option: VsCode extension Sphinx-Needs-VsCode.
Improvement: Added configuration option needs_report_dead_links, which can deactivate log messages of outgoing dead links. (issue #920)
Improvement: Configuration option needs_allow_unsafe_filters added, which allows unsafe filter for Filter function. (issue #831)
1.2.2¶
Released: 08.02.2023
Bugfix: Changed needed version of jsonschema-lib to be not so strict. (PR #871)
1.2.1¶
Released: 08.02.2023
1.2.0¶
Released: 24.01.2023
Bugfix: Allowing newer versions of jsonschema. (PR #848)
Improvement: Adds list2need directive, which allows to create simple needs from list. (issue #854)
1.1.1¶
Released: 21.12.2022
Bugfix: Removed outdated JS codes that handles the collapse button. (issue #840)
Improvement: Write autogenerated images into output folder (issue #413)
Improvement: Added vector output support to need figures. (issue #815).
Improvement: Introduce the jinja function ref for needuml. (issue #789)
Bugfix: Needflow fix bug in child need handling. (issue #785).
Bugfix: Needextract handles image and download directives correctly. (issue #818).
Bugfix: Needextract handles substitutions correctly. (issue #835).
1.1.0¶
Released: 22.11.2022
Bugfix: Expand/Collapse button does not work. (issue #795).
Bugfix: singlehtml and latex related builders are working again. (issue #796).
Bugfix: Needextend throws the same information 3 times as part of a single warning. (issue #747).
Improvement: Memory consumption and runtime improvements (issue #790).
Improvement: Obfuscate HTTP authentication credentials from log output. (issue #759)
Bugfix: needflow: nested needs on same level throws PlantUML error. (issue #799)
1.0.3¶
Released: 08.11.2022
Improvement: Fixed needextend error handling by adding a strict-mode option to it. (issue #747)
Improvement: Fixed issue with handling needs-variants by default. (issue #776)
Improvement: Performance fix needs processing. (issue #756)
Improvement: Performance fix for needflow. (issue #760)
Improvement: Fixed rendering issue with the debug layout. (issue #721)
Improvement: Added needs_show_link_id.
Improvement: Supported arguments as filter string for needextract. (issue #688)
Improvement: Added needs_render_context configuration option which enables you to use custom data as the context when rendering Jinja templates or strings. (issue #704)
Improvement: Supported
target_url
for needs_external_needs. (issue #701)Bugfix: Fixed needuml key shown in need meta data by providing internal need option arch. (issue #687)
Improvement: Included child needs inside their parent need for needflow. (issue #714)
Improvement: Supported generate need ID from title with needs_id_from_title. (issue #692)
Improvement: Supported download
needs.json
for needimport. (issue #715)Bugfix: Fixed import() be included in needarch. (issue #730)
Bugfix: Needuml: uml() call circle leads to an exception NeedArch Loop Example. (issue #731)
Improvement: needarch provide need() function to get “need data”. (issue #732)
Improvement: needuml - flow() shall return plantuml text without newline. (issue #737)
Bugfix: Needuml used but “sphinxcontrib.plantuml” not installed leads to exception (issue #742)
Improvement: better documentation of mixing orientation and coloring in needs_extra_links (issue #764)
Bugfix: Needarch: Fixed import() function to work with new implemented flow() (#737). (issue #752)
Bugfix: Needtable: generate id for nodes.table (issue #434)
Improvement: Updated pantuml in test folder to same version as in doc folder (issue #765)
1.0.2¶
Released: 22.09.2022
Improvement: Added support for variants handling for need options. (issue #671)
Improvement: Added Jinja support for need content via the jinja_content option. (issue #678)
Improvement: Added checks and warnings for needimport and needs_external_needs. (issue #624)
Improvement: Support for needs_string_links in needtable. (issue #535)
Improvement: Added key option for needuml.
Bugfix: Removed default setting allowmixing for needuml. (issue #649)
Bugfix: Fixed the collapse button issue for needs including nested needs. (issue #659)
Bugfix: Fixed needextract filter options issue involved with need_part / np. (issue #651)
Improvement: Added save option for needuml.
Improvement: Added builder needumls and config option needs_build_needumls in conf.py.
Improvement: Added filter function for needuml.
Improvement: Renamed jinja function need to flow for needuml.
Improvement: Added directive needarch.
Improvement: Added configuration option needs_ide_snippets_id to support custom need ID for VS Code Extension snippets.
Improvement: Provides jinja function import(need_links_option_name) for needarch to execute uml(id) automatically for all the links defined in the need links options.
Improvement: Added configuration needs_ide_directive_snippets to support custom directive snippets for IDE features. (issue #640)
Bugfix: Updated pip install URLs in Dockerfile. (issue #673)
Improvement: Providing IDE features support for ide_myst.
1.0.1¶
Released: 11.07.2022
Notice: Sphinx <5.0 is no longer supported.
Notice: Docutils <0.18.1 is no longer supported.
Improvement: Provides needuml for powerful, reusable Need objects.
Improvement: Provides needreport for documenting configuration used in a Sphinx-Needs project’s conf.py.
Improvement: Provides initial support for Sphinx-Needs IDE language features. (PR #584)
Improvement: Support snippet for auto directive completion for Sphinx-Needs IDE language features.
Improvement: Added show_top_sum to Needbar and make it possible to rotate the bar labels. (issue #516)
Improvement: Added needs_constraints option. Constraints can be set for individual needs and describe properties a need has to meet.
Bugfix: Fixed lsp needs.json path check. (issue #603, issue #633)
Bugfix: Support embedded needs in embedded needs. (issue #486)
Bugfix: Correct references in needtables to be external or internal instead of always external.
Bugfix: Correct documentation and configuration in tags to list type.
Bugfix: Handle overlapping labels in needpie. (issue #498)
Bugfix: needimport uses source-folder for relative path calculation (instead of confdir).
0.7.9¶
Released: 10.05.2022
Improvement: Add permanent link layout function. (issue #390)
Improvement: Support for Sphinx-Needs Docker Image. (issue #531)
Bugfix: needextract not correctly rendering nested needs. (issue #329)
0.7.8¶
Released: 29.03.2022
Improvement: Provides line number info for needs node. (issue #499)
Bugfix: needpie causing a crash in some cases on newer matplotlib versions. (issue #513, issue #517)
Bugfix: needpie takes need-parts in account for filtering. (issue #514)
Bugfix: Empty and invalid
need.json
files throw user-friendly exceptions. (issue #441)
0.7.7¶
Released: 04.03.2022
Bugfix:
need
role supporting lower and upper IDs. (issue #508)Bugfix: Correct image registration to support build via Sphinx API. (issue #505)
Bugfix: Correct css/js file registration on windows. (issue #455)
0.7.6¶
Released: 28.02.2022
Improvement: Filter function support arguments. (issue #429)
Improvement: Adds needs_build_json config option to build
needs.json
in parallel to other output formats. (issue #485)Improvement: Migrate tests to Pytest and Sphinx internal testing structure. (issue #471)
Bugfix: needs supports incremental build (no doctree deletion). (issue #481)
Bugfix: needs_external_needs working with need. (issue #483)
0.7.5¶
Released: 21.01.2022
Improvement: needbar is introduced (issue #452)
Improvement: needs_external_needs supports relative path for
base_url
.Improvement:
needs.json
schema gets checked during a needimport (issue #456)Improvement: Supports Filter function for needpie (issue #400)
Bugfix: Changed needgantt strftime format string according to C89 defined value. (issue #445)
Bugfix: needpie option :legend: is correctls rendered (issue #448)
Bugfix: needpie figures are closed after creation, to free memory and suppress matplotlib warning (issue #450)
Bugfix: Added implementation for simple_footer grid in Layouts Grids (issue #457)
Bugfix: Changed needs_external_needs Fix issue when loading needs from URL. (issue #459)
Bugfix: Changed needs_external_needs getting from URL was using parameter related to local file. (issue #458)
0.7.4¶
Released: 30.11.2021
Improvement: Adds debug flag for needservice.
Improvement: Better css table handling.
Improvement: Adds class to needtable to set own css classes for tables. (issue #421)
Improvement: Adds needs_string_links to support easy string2link transformations. (issue #404)
Improvement: Adds colwidths to needtable directive, to allow the definition of column widths. (issue #402)
0.7.3¶
Released: 08.11.2021
Improvement: Schema check for
need.json
files implemented.Improvement: New option for
needtable
and co: Filter function, which allows to reference and use python code as filter code from external files (issue #340)Bugfix: Fixed needs handling warnings about missing needs.json when needs_file not configured (issue #340)
Bugfix: unstable build with needs_external_needs (issue #399)
Bugfix: needs_external_needs reads external need status now and warnings gets not checked for needs_external_needs (issue #375)
0.7.2¶
Released: 08.10.2021
Improvement: New config option needs_builder_filter to define a filter for the needs builder. (issue #342)
Improvement: Added option
json_path
for needs_external_needs to support external needs from localneeds.json
files. (issue #339)Improvement: Providing needs_table_classes to allow to set custom table css classes, to better support themes like ReadTheDocs. (issue #305)
Improvement: Supporting user defined filter code function for needs_warnings (issue #345)
Improvement: Supporting caption for needtable (issue #348)
Improvement: New config option needs_filter_data to allow to use custom data inside a Filter string (issue #317)
Improvement: API to register warnings (issue #343)
Bugfix: Scrolling tables improved and ReadTheDocs Tables fixed (issue #305)
Bugfix: needtable need parts ‘id’ column is not linked (issue #336)
Bugfix: needtable need parts ‘incoming’ column is empty (issue #336)
Bugfix: needs_warnings not written to error log. (issue #344)
Improvement: Providing needs_warnings_always_warn to raise sphinx-warnings for each not passed needs_warnings. (issue #344)
Bugfix: needimport relative path not consistent to Sphinx default directives. (issue #351)
0.7.1¶
Released: 21.07.2021
Improvement: Support for parallel sphinx-build when using
-j
option (issue #319)Improvement: Better
eval()
handling for filter strings (issue #328)Improvement: Internal performance measurement script
Improvement: Profiling support for selected functions
0.7.0¶
Released: 06.07.2021
Improvement: Providing needs_external_needs to allow usage and referencing of external needs. (issue #137)
Improvement: New directive needextend to modify or extend existing needs. (issue #282)
Improvement: Allowing Custom column titles for needtable. (issue #299)
Bugfix: needextend does not support usage of internal options. (issue #318)
Bugfix: needtable shows attributes with value
False
again.Bugfix:
:hide:
and:collapse: True
are working inside needimport. (issue #284, issue #294)Bugfix: needpie amount labels get calculated correctly. (issue #297)
0.6.3¶
Released: 18.06.2021
Improvement: Dead links (references to not found needs) are supported and configurable by allow_dead_links. (issue #116)
Improvement: Introducing need_func to execute Dynamic functions inline. (issue #133)
Improvement: Support for multiline_option in templates.
Bugfix: needflow: links for need-parts get correctly calculated. (issue #205)
Bugfix: CSS update for ReadTheDocsTheme to show tables correctly. (issue #263)
Bugfix: CSS fix for needtable style_row. (issue #195)
Bugfix:
current_need
var is accessible in all need-filters. (issue #169)Bugfix: Sets defaults for color and style of need type configuration, if not set by user. (issue #151)
Bugfix: needtable shows horizontal scrollbar for tables using datatables style. (issue #271)
Bugfix: Using
id_complete
instead ofid
in filter code handling. (issue #156)Bugfix: Dynamic Functions registration working for external extensions. (issue #288)
0.6.2¶
Released: 30.04.2021
Improvement: Parent needs of nested needs get collected and are available in filters. (issue #249)
Bugfix: Copying static files during sphinx build is working again. (issue #252)
Bugfix: Link function for layouts setting correct text. (issue #251)
0.6.1¶
Released: 23.04.2021
Support: Removes support for Sphinx version <3.0 (Sphinx 2.x may still work, but it gets not tested).
Improvement: Internal change to poetry, nox and github actions. (issue #216)
Bugfix: Need-service calls get mocked during tests, so that tests don’t need reachable external services any more.
Bugfix: No warning is thrown any more, if needservice can’t find a service config in conf.py (issue #168)
Bugfix: Needs nodes get
ids
set directly, to avoid empty ids given by sphinx or other extensions for need-nodes. (issue #193)Bugfix: needimport supports extra options and extra fields. (issue #227)
Bugfix: Checking for ending / of given github api url. (issue #187)
Bugfix: Using correct indention for pre and post_template function of needs.
Bugfix: Certain log message don’t use python internal id any more. (issue #225)
Bugfix: JS-code for meta area collapse is working again. (issue #242)
0.6.0¶
Improvement: Directive needservice added, which allow to include data from external services like Jira or github. See also Services (issue #163)
Improvement: GitHub services added to fetch issues, pr or commits from GitHub or GitHub Enterprise.
Bugfix: Role need_outgoing shows correct link instead of None (issue #160)
0.5.6¶
Bugfix: Dynamic function registration via API supports new internal function handling (issue #147)
Bugfix: Deactivated linked gantt elements in needgantt, as PlantUML does not support them in its latest version (not beta).
0.5.5¶
Improvement: Added needsequence directive. (issue #144)
Improvement: Added needgantt directive. (issue #146)
Improvement: Added two new need-options: duration and completion
Improvement: Configuration option needs_duration_option and needs_completion_option added
Bugfix: Using of tags.has() in conf.py does not raise an exception any more. (issue #142)
Improvement: Clean up of internal configuration handling and avoiding needs_functions to get pickled by sphinx.
0.5.4¶
Improvement: Added options pre_template and post_template for needs. (issue #139)
Bugfix: Setting correct default value for needs_statuses (issue #136)
Bugfix: Dynamic functions can be used in links (text and url) now.
0.5.3¶
Improvement: Added
transparent
for transparent background to needflow configurations.Improvement: needflow uses directive argument as caption now.
Improvement: Added option align to align needflow images.
Improvement: Added option scale to scale needflow images. (issue #127)
Improvement: Added option highlight to needflow. (issue #128)
Improvement: need_count supports ratio calculation. (issue #131)
Improvement: needlist, needtable and needflow support Filter code. (issue #132)
Improvement: needflow caption is a link to the original image file. (issue #129)
Bugfix: template can now be set via needs_global_options.
Bugfix: Setting correct urls for needs in needflow charts.
Bugfix: Setting correct image candidates (issue #134)
0.5.2¶
Improvement: Sphinx-Needs configuration gets checked before build. (issue #118)
Improvement:
meta_links_all
layout function now supports an exclude parameterImprovement: needflow’s connection line and arrow type can be configured.
Improvement: Configurations added for needflow. Use needs_flow_configs to define them and config for activation.
Improvement: needflow option debug added, which prints the generated PlantUML code after the flowchart.
Improvement: Supporting Need-Templates by providing need option template and configuration option needs_template_folder. (issue #119)
Bugfix: needs_global_options handles None values correctly.
style
can now be set.Bugfix: needs_title_from_content takes
\n
and.
as delimiter.Bugfix: Setting css-attribute
white-space: normal
for all need-tables, which is set badly in some sphinx-themes. (Yes, I’m looking at you ReadTheDocs theme…)Bugfix:
meta_all
layout function also outputs extra links and the no_links parameter now works as expectedBugfix: Added need-type as css-class back on need. Css class name is
needs_type_(need_type attribute)
. (issue #124)Bugfix: Need access inside list comprehensions in Filter string is now working.
0.5.1¶
Improvement: Added needextract directive to mirror existing needs for special outputs. (issue #66)
Improvement: Added new styles
discreet
anddiscreet_border
.Bugfix: Some minor css fixes for new layout system.
0.5.0¶
Improvement: Introduction of needs Layouts & Styles.
Improvement: Added config options needs_layouts and needs_default_layout.
Improvement: Added needpie which draws pie-charts based on Filter string.
Improvement: Added config option needs_warnings. (issue #110)
Bugfix: Need css style name is now based on need-type and not on the longer, whitespace-containing type name. Example:
need-test
instead of not validneed-test case
. (issue #108)Bugfix: No more exception raise if
copy
value not set inside needs_extra_links.Improvement: Better log message, if required id is missing. (issue #112)
Removed: Configuration option needs_collapse_details. This is now realized by Layouts.
Removed: Configuration option needs_hide_options. This is now realized by Layouts.
Removed: Need option need_hide_status. This is now realized by Layouts.
Removed: Need option need_hide_tags. This is now realized by Layouts.
WARNING: This version changes a lot the html output and therefore the needed css selectors. So if you are using custom css definitions you need to update them.
0.4.3¶
Improvement: Role need supports standard sphinx-ref syntax. Example:
:need:`custom name <need_id>`
Improvement: Added needs_global_options to set values of global options only under custom circumstances.
Improvement: Added sorting to needtable. See sort for details.
Improvement: Added dynamic function links_from_content to calculated links to other needs automatically from need-content. (issue #98)
Improvement: Dynamic function copy supports uppercase and lowercase transformation.
Improvement: Dynamic function copy supports filter_string.
Bugfix: Fixed corrupted Dynamic functions handling for
tags
and other list options. (issue #100)Bugfix: Double entries for same need in needtable fixed. (issue #93)
0.4.2¶
Improvement: Added
signature
information to need-object. Usable inside Filter string. Mainly needed by Sphinx-Test-Reports to link imported test cases to needs documented by sphinx-autodoc.
0.4.1¶
0.4.0¶
Improvement: Provides API for other sphinx-extensions. See Python API for documentation.
Improvement: Added Support page.
Bugfix: Fixed deprecation warnings to support upcoming Sphinx3.0 API.
0.3.15¶
Improvement: In filter operations, all needs can be accessed by using keyword
needs
.Bugfix: Removed prefix from normal needs for needtable (issue #97)
0.3.14¶
Improvement: Added config option needs_role_need_max_title_length to define the maximum title length of referenced needs. (issue #95)
0.3.13¶
Bugfix: Filters on needs with
id_parent
orid_complete
do not raise an exception any more and filters gets executed correctly.
0.3.12¶
Improvement: Tables can be sorted by any alphanumeric option. (issue #92)
Improvement: need_part / np are now embedded in their parent need, if needflow is used. (issue #83)
Bugfix: Links to need_part / np are no longer rendered to parent need, instead the link goes directly to the need_part. (issue #91)
Bugfix: Links in needflow get shown again by default (issue #90)
0.3.11¶
Improvement: Added config option needs_extra_links to define additional link types like blocks, tested by and more. Supports also style configuration and custom presentation names for links.
Improvement: Added export_id option for filter directives to export results of filters to
needs.json
.Improvement: Added config option needs_flow_show_links and related needflow option show_link_names.
Improvement: Added config option needs_flow_link_types and related needflow option link_types.
Bugfix: Unicode handling for Python 2.7 fixed. (issue #86)
0.3.10¶
Bugfix: type was missing in output of builder needs (issue #79)
Bugfix: needs_functions parameter in conf.py created a sphinx error, if containing python methods. Internal workaround added, so that usage of own Dynamic functions stays the same as in prior versions (issue #78)
0.3.9¶
Bugfix: Grubby tag/link strings in needs, which define empty links/tags, produce a warning now.
Bugfix: Better logging of document location, if a filter string is not valid.
Bugfix: Replaced all print-statements with sphinx warnings.
0.3.8¶
Improvement: need_part / np has now attributes id_parent and id_complete, which can be referenced in Filter string.
Improvement: needtable supports presentation of filtered need_part / np (without showing parent need).
0.3.7¶
Improvement: Filter string now supports the filtering of need_part / np.
Improvement: The ID of a need is now printed as link, which can easily be used for sharing. (issue #75)
Bugfix: Filter functionality in different directives are now using the same internal filter function.
Bugfix: Reused IDs for a need_part / np are now detected and a warning gets printed. (issue #74)
0.3.6¶
Improvement: Added needtable option show_parts.
Improvement: Added configuration option needs_part_prefix.
Improvement: Added docname to output file of builder needs
Bugfix: Added missing needs_import template to MANIFEST.ini.
0.3.5¶
Bugfix: A need_part / np without a given ID gets a random id based on its content now.
Bugfix: Calculation of outgoing links does not crash, if need_parts are involved.
0.3.4¶
Bugfix: Need representation in PDFs were broken (e.g. all meta data on one line).
0.3.3¶
Bugfix: Latex and Latexpdf are working again.
0.3.2¶
Bugfix: Links to parts of needs (need_part / np) are now stored and presented as links incoming of target link.
0.3.1¶
Improvement: Added dynamic function check_linked_values.
Improvement: Added dynamic function calc_sum.
Improvement: Added role need_count, which shows the amount of found needs for a given filter-string.
- Bugfix: Links to need_part / np in needflow are now shown correctly as extra line between
need_parts containing needs.
Bugfix: Links to need_part / np in needtable are now shown and linked correctly in tables.
0.3.0¶
Improvement: Dynamic functions are now available to support calculation of need values.
Improvement: needs_functions can be used to register and use own dynamic functions.
Improvement: Added needs_global_options to set need values globally for all needs.
Improvement: Added needs_hide_options to hide specific options of all needs.
Bugfix: Removed needs are now deleted from existing needs.json (issue #68)
Removed: needs_template and needs_template_collapse are no longer supported.
0.2.5¶
Bugfix: Fix for changes made in 0.2.5.
0.2.4¶
Bugfix: Fixed performance issue (issue #63)
0.2.3¶
Improvement: Titles can now be made optional. See needs_title_optional. (issue #49)
Improvement: Titles be auto-generated from the first sentence of a requirement. See needs_title_from_content and title_from_content. (issue #49)
Improvement: Titles can have a maximum length. See needs_max_title_length. (issue #49)
0.2.2¶
Improvement: The sections, to which a need belongs, are now stored, filterable and exported in
needs.json
. See updated filter. (PR #53 )Improvement: Project specific options for needs are supported now. See needs_extra_options. (PR #48 )
Bugfix: Logging fixed (issue #50 )
Bugfix: Tests for custom styles are now working when executed with all other tests (PR #47)
0.2.1¶
Bugfix: Sphinx warnings fixed, if need-collapse was used. (issue #46)
Bugfix: dark.css, blank.css and common.css used wrong need-container selector. Fixed.
0.2.0¶
Deprecated:
needfilter
is replaced by needlist, needtable or needflow. Which support additional options for related layout.Improvement: Added needtable directive.
Improvement: Added DataTables support for needtable (including table search, excel/pdf export and dynamic column selection).
Improvement: Added needs_id_regex, which takes a regular expression and which is used to validate given IDs of needs.
Improvement: Added meta information shields on documentation page
Improvement: Added more examples to documentation
Bugfix: Care about unneeded separator characters in tags (issue #36)
Bugfix: Avoiding multiple registration of resource files (js, css), if sphinx gets called several times (e.g. during tests)
Bugfix: Needs with no status shows up on filters (issue #45)
Bugfix: Supporting Sphinx 1.7 (issue #41)
0.1.49¶
0.1.48¶
Improvement: Added configuration option needs_role_need_template.
Bugfix: Referencing not existing needs will result in build warnings instead of a build crash.
- Refactoring: needs development files are stored internally under sphinxcontrib/needs, which is in sync with
most other sphinxcontrib-packages.
0.1.47¶
Bugfix: dark.css was missing in MANIFEST.in.
Improvement: Better output, if configured needs_css file can not be found during build.
0.1.46¶
Bugfix: Added python2/3 compatibility for needs_import.
0.1.45¶
Bugfix: needs with no status are handled the correct way now.
0.1.44¶
Bugfix: Import statements are checked, if Python 2 or 3 is used.
0.1.43¶
Improvement: Added “dark.css” as style
Bugfix: Removed “,” as as separator of links in need presentation.
0.1.42¶
Improvement: Added config parameter needs_css, which allows to set a css file.
Improvement: Most need-elements (title, id, tags, status, …) got their own html class attribute to support custom styles.
Improvement: Set default style “modern.css” for all projects without configured needs_css parameter.
0.1.41¶
Improvement: Added config parameters needs_statuses and needs_tags to allow only configured statuses/tags inside documentation.
Bugfix: Added LICENSE file (MIT)
0.1.40¶
Bugfix: Removed jinja activation
0.1.39¶
Bugfix: Added missing needimport_template.rst to package
Bugfix: Corrected version param of needimport
0.1.38¶
- Improvement: :links:, :tags: and other list-based options can handle “,” as delimiter
(beside documented “;”). No spooky errors are thrown any more if “,” is used accidentally.
0.1.37¶
Bugfix: Implemented 0.1.36 bugfix also for
needfilter
and needimport.
0.1.36¶
Bugfix: Empty :links: and :tags: options for need items raise no error during build.
0.1.35¶
Improvement/Bug: Updated default node_template to use less space for node parameter representation
Improvement: Added :filter: option to needimport directive
Bugfix: Set correct default value for need_list option. So no more warnings should be thrown during build.
Bugfix: Imported needs gets sorted by id before adding them to the related document.
0.1.34¶
Improvement: New option tags for needimport directive
Bugfix: Handling of relative paths in needs builder
0.1.33¶
New feature: Directive needimport implemented
Improvement: needs-builder stores needs.json for all cases in the build directory (like _build/needs/needs.json) (See issue)
Bugfix: Wrong version in needs.json, if an existing needs.json got imported
Bugfix: Wrong need amount in initial needs.json fixed
0.1.32¶
Bugfix: Setting correct working directory during conf.py import
Bugfix: Better config handling, if Sphinx builds gets called multiple times during one single python process. (Configs from prio sphinx builds may still be active.)
Bugifx: Some clean ups for using Sphinx >= 1.6
0.1.31¶
Bugfix: Added missing dependency to setup.py: Sphinx>=1.6
0.1.30¶
Improvement: Builder needs added, which exports all needs to a json file.
0.1.29¶
Bugfix: Build has crashed, if sphinx-needs was loaded but not a single need was defined.
0.1.28¶
- Bugfix: Added support for multiple sphinx projects initialisations/builds during a single python process call.
(Reliable sphinx-needs configuration separation)
0.1.27¶
New config: needs_show_link_type
New config: needs_show_link_title
0.1.26¶
- Bugfix: Working placement of “,” for links list produced by roles need_outgoing
and need_incoming.
0.1.25¶
Restructured code
Restructured documentation
Improvement: Role need_outgoing was added to print outgoing links from a given need
Improvement: Role need_incoming was added to print incoming links to a given need
0.1.24¶
Bugfix: Reactivated jinja execution for documentation.
0.1.23¶
Improvement: complex filter for needfilter directive supports regex searches.
Improvement: complex filter has access to nearly all need variables (id, title, content, …)`.
Bugfix: If a duplicated ID is detected an error gets thrown.
0.1.22¶
Improvement: needfilter directives supports complex filter-logic by using parameter Filtering needs.
0.1.21¶
Improvement: Added word highlighting of need titles in linked pages of svg diagram boxes.
0.1.20¶
Bugfix for custom needs_types: Parameter in conf.py was not taken into account.
0.1.19¶
Added configuration parameter needs_id_required.
Backwards compatibility changes:
Reimplemented needlist as alias for
needfilter
Added need directive/need as part of the default needs_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