diff --git a/docs/changelog.rst b/docs/changelog.rst index f3f6d1de6..2af0d8b8d 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -10,6 +10,9 @@ License ----- :Released: under development +* Bugfix: :ref:`needextract` not correctly rendering nested :ref:`need`s. + (`#329 `_) + 0.7.8 ----- :Released: 29.03.2022 @@ -18,9 +21,9 @@ License (`#499 `_) * Bugfix: :ref:`needpie` causing a crash in some cases on newer matplotlib versions. (`#513 `_, -* Bugfix: :ref:`needpie` takes need-parts in account for filtering. - (`#514 `_, `#517 `_) +* Bugfix: :ref:`needpie` takes need-parts in account for filtering. + (`#514 `_) * Bugfix: Empty and invalid ``need.json`` files throw user-friendly exceptions. (`#441 `_) diff --git a/sphinxcontrib/needs/directives/need.py b/sphinxcontrib/needs/directives/need.py index a0591f397..db48bf7f0 100644 --- a/sphinxcontrib/needs/directives/need.py +++ b/sphinxcontrib/needs/directives/need.py @@ -308,7 +308,7 @@ def print_need_nodes(app, doctree, fromdocname): layout = need_data["layout"] or app.config.needs_default_layout - build_need(layout, node_need, app) + build_need(layout, node_need, app, fromdocname=fromdocname) def check_links(env): diff --git a/sphinxcontrib/needs/layout.py b/sphinxcontrib/needs/layout.py index 3b13db2dc..caf4b6852 100644 --- a/sphinxcontrib/needs/layout.py +++ b/sphinxcontrib/needs/layout.py @@ -42,6 +42,7 @@ def create_need(need_id, app: Sphinx, layout=None, style=None, docname=None): node_container = nodes.container() node_inner = needs[need_id]["content_node"] + node_container.append(node_inner) # Resolve internal refernces. # This is done for original need content automatically. # But as we are working on a copy, we have to trigger this on our own. @@ -51,17 +52,20 @@ def create_need(need_id, app: Sphinx, layout=None, style=None, docname=None): # resolve_references() ignores the given docname and takes the docname from the pending_xref node. # Therefore we need to manipulate this first, before we can ask Sphinx to perform the normal # reference handling for us. - replace_pending_xref_refdoc(node_inner, docname) - env.resolve_references(node_inner, docname, env.app.builder) - - node_container.append(node_inner) + replace_pending_xref_refdoc(node_container, docname) + env.resolve_references(node_container, docname, env.app.builder) - node_inner.attributes["ids"].append(need_id) + node_container.attributes["ids"].append(need_id) layout = layout or need_data["layout"] or app.config.needs_default_layout style = style or need_data["style"] or app.config.needs_default_style - build_need(layout, node_inner, app, style, docname) + build_need(layout, node_container, app, style, docname) + + # set the layout and style for the new need + node_container[0].attributes = node_container.parent.children[0].attributes + + node_container.attributes["ids"] = [] return node_container diff --git a/tests/doc_test/needextract_with_nested_needs/Makefile b/tests/doc_test/needextract_with_nested_needs/Makefile new file mode 100644 index 000000000..47330b89c --- /dev/null +++ b/tests/doc_test/needextract_with_nested_needs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +SPHINXPROJ = needstestdocs +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) \ No newline at end of file diff --git a/tests/doc_test/needextract_with_nested_needs/conf.py b/tests/doc_test/needextract_with_nested_needs/conf.py new file mode 100644 index 000000000..18d9010b0 --- /dev/null +++ b/tests/doc_test/needextract_with_nested_needs/conf.py @@ -0,0 +1,159 @@ +# +# needs test docs documentation build configuration file, created by +# sphinx-quickstart on Tue Mar 28 11:37:14 2017. +# +# This file is execfile()d with the current directory set to its +# containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +import os +import sys + +sys.path.insert(0, os.path.abspath("../../sphinxcontrib")) + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +# +# needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. + +extensions = ["sphinxcontrib.needs"] + +needs_id_regex = "^[A-Za-z0-9_]" + +needs_types = [ + {"directive": "story", "title": "User Story", "prefix": "US_", "color": "#BFD8D2", "style": "node"}, + {"directive": "spec", "title": "Specification", "prefix": "SP_", "color": "#FEDCD2", "style": "node"}, + {"directive": "impl", "title": "Implementation", "prefix": "IM_", "color": "#DF744A", "style": "node"}, + {"directive": "test", "title": "Test Case", "prefix": "TC_", "color": "#DCB239", "style": "node"}, +] + +plantuml = "java -jar %s" % os.path.join(os.path.dirname(__file__), "..", "utils", "plantuml.jar") +plantuml_output_format = "svg" + +# Add any paths that contain templates here, relative to this directory. +templates_path = ["_templates"] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +# source_suffix = ['.rst', '.md'] +source_suffix = ".rst" + +# The master toctree document. +master_doc = "index" + +# General information about the project. +project = "needs test docs" +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. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This patterns also effect to html_static_path and html_extra_path +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = "sphinx" + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = False + +# -- Options for HTML output ---------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = "alabaster" + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# +# html_theme_options = {} + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +# html_static_path = ["_static"] + +# -- Options for HTMLHelp output ------------------------------------------ + +# Output file base name for HTML help builder. +htmlhelp_basename = "needstestdocsdoc" + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, "needstestdocs.tex", "needs test docs Documentation", "team useblocks", "manual"), +] + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [(master_doc, "needstestdocs", "needs test docs Documentation", [author], 1)] + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + ( + master_doc, + "needstestdocs", + "needs test docs Documentation", + author, + "needstestdocs", + "One line description of project.", + "Miscellaneous", + ), +] diff --git a/tests/doc_test/needextract_with_nested_needs/index.rst b/tests/doc_test/needextract_with_nested_needs/index.rst new file mode 100644 index 000000000..a72356065 --- /dev/null +++ b/tests/doc_test/needextract_with_nested_needs/index.rst @@ -0,0 +1,31 @@ +Test +==== + +.. toctree:: + + needextract + +.. spec:: Test spec + :id: SPEC_1 + + Another, child spec + + .. spec:: Child spec + :id: SPEC_1_1 + + awesome child spec. + and now a grandchild spec + + .. spec:: Grandchild spec + :id: SPEC_1_1_1 + + awesome grandchild spec. + + another grandchild spec + + .. spec:: Grandchild spec + :id: SPEC_1_1_2 + + awesome grandchild spec number 2. + + Some parent text \ No newline at end of file diff --git a/tests/doc_test/needextract_with_nested_needs/make.bat b/tests/doc_test/needextract_with_nested_needs/make.bat new file mode 100644 index 000000000..489ed7dfd --- /dev/null +++ b/tests/doc_test/needextract_with_nested_needs/make.bat @@ -0,0 +1,36 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build +set SPHINXPROJ=needstestdocs + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% + +:end +popd diff --git a/tests/doc_test/needextract_with_nested_needs/needextract.rst b/tests/doc_test/needextract_with_nested_needs/needextract.rst new file mode 100644 index 000000000..f2420c972 --- /dev/null +++ b/tests/doc_test/needextract_with_nested_needs/needextract.rst @@ -0,0 +1,5 @@ +Needextract test +================ + +.. needextract:: + :filter: id == "SPEC_1" diff --git a/tests/test_needextract_with_nested_needs.py b/tests/test_needextract_with_nested_needs.py new file mode 100644 index 000000000..5e660129c --- /dev/null +++ b/tests/test_needextract_with_nested_needs.py @@ -0,0 +1,30 @@ +from pathlib import Path + +import pytest + + +@pytest.mark.parametrize( + "test_app", [{"buildername": "html", "srcdir": "doc_test/needextract_with_nested_needs"}], indirect=True +) +def test_needextract_with_nested_needs(test_app): + app = test_app + app.build() + needextract_html = Path(app.outdir, "needextract.html").read_text() + + # ensure that the needs exist and that their hrefs point to the correct location + assert ( + 'SPEC_1' + in needextract_html + ) + assert ( + 'SPEC_1_1' + in needextract_html + ) + assert ( + 'SPEC_1_1_1' in needextract_html + ) + assert ( + 'SPEC_1_1_2' in needextract_html + )