Demo page details

Page source code: demo_details.rst

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
{% set page="demo_details.rst" %}
{% include "demo_page_header.rst" with context %}

🔍 Demo details
===============
This page gives some details about extensions, configurations and other important files, which were used
to define this documentation project.


Extensions
----------

:`Sphinx-Needs <https://sphinx-needs.readthedocs.io>`__: 
    Used to create and link objects in the documentation, mainly requirements, specifications and tests.
    Provides also features to filter and represent the objects in tables and flow charts.

:`Sphinx-Test-Reports <https://sphinx-test-reports.readthedocs.io>`__:
    Loads test-results/runs into a Sphinx project, by reading a junit-based result file.
    Is based on top of Sphinx-Needs.

:`Sphinx-Design <https://sphinx-design.readthedocs.io>`__:
    Provides features to layout the content or to use dropdown, buttons or tabs.

:`Sphinx-Immaterial <https://jbms.github.io/sphinx-immaterial/>`__:
    The Sphinx theme for this documentation. 

:`Sphinxcontrib-PlantUML <https://github.com/sphinx-contrib/plantuml>`__:
    Allows to use `PlantUML <https://plantuml.com/>`__ inside a Sphinx project. Used to create all kinds of diagrams.
    Also Sphinx-Needs features like ``needflow`` are based on it.

:`Sphinx-SimplePDF <https://sphinx-simplepdf.readthedocs.io/>`__:
    Provides a Sphinx builder to create a beautiful PDF out of the documentation.

:`Sphinx-Preview <https://sphinx-preview.readthedocs.io>`__:
    Allows you to get a quick preview of a link without leaving the page.
    Especially useful for getting a quick impression of linked Sphinx-Needs objects.

Configurations
--------------

requirements.txt
~~~~~~~~~~~~~~~~
Used to install all needed packages for the used Python environment.

Can be used like ``pip install -r requirements.txt``

.. literalinclude:: ../requirements.txt
   :language: text
   :linenos:


conf.py
~~~~~~~
The whole configuration file of this project.

Details are explained as comments in the file itself.

.. literalinclude:: conf.py
   :language: python
   :linenos:

Templates
---------

req_post
~~~~~~~~
Adds the "Object traceability details" under each requirement.

.. literalinclude:: needs_templates/req_post.need
   :language: rst
   :linenos:

spec_post
~~~~~~~~~
Adds the "Object traceability details" under each specification.

The used filters are slightly different from the ones used for requirements, therefore an extra template is used.

.. literalinclude:: needs_templates/spec_post.need
   :language: rst
   :linenos:

Includes
--------

demo_page_header
~~~~~~~~~~~~~~~~

This is used to add the "Demo page details" on top of each page.

.. literalinclude:: demo_page_header.rst
   :language: rst
   :linenos:

🔍 Demo details

This page gives some details about extensions, configurations and other important files, which were used to define this documentation project.

Extensions

Sphinx-Needs:

Used to create and link objects in the documentation, mainly requirements, specifications and tests. Provides also features to filter and represent the objects in tables and flow charts.

Sphinx-Test-Reports:

Loads test-results/runs into a Sphinx project, by reading a junit-based result file. Is based on top of Sphinx-Needs.

Sphinx-Design:

Provides features to layout the content or to use dropdown, buttons or tabs.

Sphinx-Immaterial:

The Sphinx theme for this documentation.

Sphinxcontrib-PlantUML:

Allows to use PlantUML inside a Sphinx project. Used to create all kinds of diagrams. Also Sphinx-Needs features like needflow are based on it.

Sphinx-SimplePDF:

Provides a Sphinx builder to create a beautiful PDF out of the documentation.

Sphinx-Preview:

Allows you to get a quick preview of a link without leaving the page. Especially useful for getting a quick impression of linked Sphinx-Needs objects.

Configurations

requirements.txt

Used to install all needed packages for the used Python environment.

Can be used like pip install -r requirements.txt

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
sphinx>=7
sphinx-needs[plotting] @ git+https://github.com/useblocks/sphinx-needs@master
sphinx-design
sphinx-immaterial
sphinxcontrib-plantuml
sphinx-autobuild
sphinx-test-reports
sphinx-simplepdf
sphinx-preview
weasyprint==60.2

conf.py

The whole configuration file of this project.

Details are explained as comments in the file itself.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
# Configuration file for the Sphinx documentation builder.
#
# For the full list of built-in configuration values, see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html
import os
import jinja2
import sys

# We need to make Python aware of our project source code, which is stored outside `/docs`, 
# under `src/`
code_path = os.path.join(os.path.dirname(__file__), "../", "src/")
sys.path.append(code_path)
print(f"CODE_PATH: {code_path}")


# -- Project information -----------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information

project = 'Sphinx-Needs Demo'
copyright = '2024, team useblocks'
author = 'team useblocks'
version = "1.0"

# -- General configuration ---------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration

# List of Sphinx extension to use.
extensions = [
    "sphinx_needs",
    "sphinx_design",
    "sphinxcontrib.plantuml",
    "sphinxcontrib.test_reports",
    "sphinx_simplepdf",
    "sphinx.ext.autodoc",
    "sphinx.ext.viewcode",
    "sphinx_preview"
]

# During a PDF build with Sphinx-SimplePDF, a special theme is used.
# But adding "sphinx_immaterial" to the extension list, the "immaterial" already
# does a lot of sphinx voodoo, which is not needed and does not work during a PDF build.
# Therefore we add it only, if a special ENV-Var is not set.
#
# As we can't ask Sphinx already in the config file, which Builder will be used, we need
# to set this information by hand, or in this case via an ENV var.
#
# To build HTML, just call ``make html
# To build PDF, call ``env PDF=1 make simplepdf"
if os.environ.get("PDF", "0") != "1":
    extensions.append("sphinx_immaterial")

###############################################################################
# SPHINX-NEEDS Config START
###############################################################################

# Build also the needs.json file with each HTML build
needs_build_json = True

# List of need type, we need in our documentation.
# Docs: https://sphinx-needs.readthedocs.io/en/latest/configuration.html#needs-types
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="person", title="Person", prefix="P_", color="#DCB239", style="actor"),
               dict(directive="team", title="Team", prefix="T_", color="#DCB239", style="node"),
               dict(directive="release", title="Release", prefix="R_", color="#DCB239", style="node"),
           ]

# Additional options, which shall be available for all need types.
# Docs: https://sphinx-needs.readthedocs.io/en/latest/configuration.html#needs-extra-options
needs_extra_options = ['role', 'contact', 'image', 'date', 'customer']

# Extra link types, which shall be available and allow need types to be linked to each other.
# We use a dedicated linked type for each type of a conncetion, for instance from 
# a specification to a requirement. This makes filtering and visualization of such connections
# much easier, as we can sure the target need of a link has always a specific type.
# Docs: https://sphinx-needs.readthedocs.io/en/latest/configuration.html#needs-extra-links
needs_extra_links = [
   {  # team -> person
      "option": "persons",
      "incoming": "is working for",
      "outgoing": "persons",
   },
   {  # req -> release
      "option": "release",
      "incoming": "contains",
      "outgoing": "release",
   },
   {  # req -> author
      "option": "author",
      "incoming": "ownes",
      "outgoing": "author",
   },
    {  # req -> req, release -> release
      "option": "based_on",
      "incoming": "supports",
      "outgoing": "based on",
   },
   {  # spec -> req
      "option": "reqs",
      "incoming": "specified by",
      "outgoing": "specifies",
   },
   {  # impl -> spec 
      "option": "implements",
      "incoming": "implemented by",
      "outgoing": "implements",
   },
   {  # test_case -> spec
      "option": "spec",
      "incoming": "test_cases",
      "outgoing": "specs",
   },
   {  # test_case -> test_run
      "option": "runs",
      "incoming": "test_cases",
      "outgoing": "runs",
   },
   {  # test_case -> spec
      "option": "specs",
      "incoming": "test_cases",
      "outgoing": "specs",
   },
]

# We force the author to set anb ID by hand.
# Otherwise Sphinx-Needs would create on based on the Need title.
# So a title change will change the ID and all set links will get invalid.
# Therefore setting a stable ID by hand is always a good idea.
# Docs: https://sphinx-needs.readthedocs.io/en/latest/configuration.html#needs-id-required
needs_id_required = True

# The format of a need gets defined here.
# In this demo project, we allow any kind of ID. 
# But it could be also much more complex. 
# For instance: `^[A-Z]{3}_[0-9]{1,4}$`, which allows IDs like "ABC_1234" or "DEA_3" only.
# Docs: https://sphinx-needs.readthedocs.io/en/latest/configuration.html#needs-id-regex
needs_id_regex = r".*"

# We override the default test-case need of Sphinx-Test-Reports, so that is called
# ``test_run`` instead.
# Docs: https://sphinx-test-reports.readthedocs.io/en/latest/configuration.html#tr-case
tr_case = ['test_run', 'testrun', 'Test-Run', 'TR_', '#999999', 'node']

# `needs_global_options` allows us to set values for Sphinx-Need objects globally, based on
# filters.
# Docs: https://sphinx-needs.readthedocs.io/en/latest/configuration.html#needs-global-options
needs_global_options = {
   # The meta-area of all Sphinx-Needs objects shall be hidden. 
   # Supported only, if a "collapse button" is used in the selected need layout.
   'collapse': "False",
   # Automatically link test-runs with test-cases.
   # We use here the dynamic function ``tr_link`` so link 2 needs, 
   # if the ID of need A is the same as the case_name of need B.
   # But we do this only for objects of type ``test``.
   # Docs: https://sphinx-test-reports.readthedocs.io/en/latest/functions.html#tr-link
   'runs': ("[[tr_link('id', 'case_name')]]", "type=='test'"),
   # By setting ``post_template``, we can add some extra content below a need object.
   # What gets added is set in the related template file under ``/needs_templates``.
   # In our case a traceability flow chart is generated, plus the same information as table.
   'post_template': [
       ("req_post", "type in ['req']"),
       ("spec_post", "type in ['spec']")
   ],
   'constraints': [
       (["status_set", "release_set"], "type in ['req']")
   ],
   'layout': [
       ('req_constraint', "type in ['req']")
   ]
}

needs_constraints = {
    "status_set": {
        "check_0": "status is not None and status in ['open', 'in progress', 'closed']",
        "severity": "LOW",
        "error_message": "Status is invalid or not set!"
    },
    "release_set": {
        "check_0": "len(release)>0",
        "severity": "CRITICAL",
        "error_message": "Requirement is not planned for any release!"
    },
}

needs_constraint_failed_options = {
    "CRITICAL": {
        "on_fail": ["warn"],
        "style": ["red_bar"],
        "force_style": False
    },

    "HIGH": {
        "on_fail": ["warn"],
        "style": ["orange_bar"],
        "force_style": False
    },

    "MEDIUM": {
        "on_fail": ["warn"],
        "style": ["yellow_bar"],
        "force_style": False
    },
    "LOW": {
        "on_fail": [],
        "style": ["blue_bar"],
        "force_style": False
    }
}

# needs_variants allows us to set specific option values based on the currently active variant.
# A use case is a different ``status``, depending on if the implementation needs to be done for 
# customer A or customer B.
# In the rst-code, the variant-values can then be set like this:
# ``:status: customer_a:open, customer_b:closed``
needs_variants = {
  "customer_a": "customer == 'A' or customer not in ['A', 'B']",
  "customer_b": "customer == 'B'"
}
# Activates variants handling for these options only.
# All other options get not checked, to save some build time, as these checks are quite time consuming.
needs_variant_options = ["author", "status"]

needs_layouts = {
    "req_constraint": {
        "grid": "simple_footer",
        "layout": {
            "head": [
                '<<meta("type_name")>>: **<<meta("title")>>** <<meta_id()>>  <<collapse_button("meta", '
                'collapsed="icon:arrow-down-circle", visible="icon:arrow-right-circle", initial=False)>> '
            ],
            "meta": ["<<meta_all(no_links=True, exclude=['constraints_error'])>>", "<<meta_links_all()>>"],
            "footer": ["**Process feedback**: <<meta('constraints_error')>>"]
        },
    },
}

###############################################################################
# SPHINX-NEEDS Config END
###############################################################################

# The config for the preview features, which allows to "sneak" into a link.
# Docs: https://sphinx-preview.readthedocs.io/en/latest/#configuration
preview_config = {
    # Add a preview icon only for this type of links
    # This is very theme and HTML specific. In this case "div-mo-content" is the content area
    # and we handle all links there.
    "selector": "div.md-content a",
    # A list of selectors, where no preview icon shall be added, because it makes often no sense.
    # For instance the own ID of a need object, or the link on an image to open the image.
    "not_selector": "div.needs_head a, h1 a, h2 a, a.headerlink, a.md-content__button, a.image-reference, em.sig-param a, a.paginate_button, a.sd-btn",
    "set_icon": True,
    "icon_only": True,
    "icon_click": True,
    "icon": "🔍",
    "width": 600,
    "height": 400,
    "offset": {
        "left": 0,
        "top": 0
    },
    "timeout": 0,
}

templates_path = ['_templates']

# List of files/folder to ignore.
# Sphinx builds all ``.rst`` files under ``/docs``, no matte if they are part
# of a toctree or not. So as we have some rst-templates, we need to tell Sphinx to ignore
# these files.
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'demo_page_header.rst', 'demo_hints']

# We bring our own plantuml jar file.
# These options tell Sphinxcontrib-PlantUML we it can find this file.
local_plantuml_path = os.path.join(os.path.dirname(__file__), "utils", "plantuml-1.2022.14.jar")
plantuml = f"java -Djava.awt.headless=true -jar {local_plantuml_path}"
# plantuml_output_format = 'png'
plantuml_output_format = "svg_img"


# -- Options for HTML output -------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output

html_theme = 'alabaster' # Sphinx Defaul Theme

# Set ``html_theme`` to ``sphinx_immaterial`` only, if we do NOT perform a PDF build.
if os.environ.get("PDF", 0) != 1:
   html_theme = 'sphinx_immaterial'

html_static_path = ['_static']

sphinx_immaterial_override_generic_admonitions = True

html_logo = "_images/sphinx-needs-logo.png"
html_theme_options = {
    "font": False,
    "icon": {
        "repo": "fontawesome/brands/github",
        "edit": "material/file-edit-outline",
    },
    "site_url": "https://jbms.github.io/sphinx-immaterial/",
    "repo_url": "https://github.com/useblocks/sphinx-needs-demo",
    "repo_name": "Sphinx-Needs Demo",
    "edit_uri": "blob/main/docs",
    "globaltoc_collapse": True,
    "features": [
        "navigation.expand",
        # "navigation.tabs",
        # "toc.integrate",
        "navigation.sections",
        # "navigation.instant",
        # "header.autohide",
        "navigation.top",
        # "navigation.tracking",
        "search.highlight",
        "search.share",
        "toc.follow",
        "toc.sticky",
        "content.tabs.link",
        "announce.dismiss",
    ],
    "palette": [
        {
            "media": "(prefers-color-scheme: light)",
            "scheme": "default",
            "primary": "blue",
            "accent": "light-cyan",
            # "toggle": {
            #     "icon": "material/lightbulb-outline",
            #     "name": "Switch to dark mode",
            # },
        },
        # {
        #     "media": "(prefers-color-scheme: dark)",
        #     "scheme": "slate",
        #     "primary": "blue",
        #     "accent": "light-cyan",
        #     "toggle": {
        #         "icon": "material/lightbulb",
        #         "name": "Switch to light mode",
        #     },
        # },
    ],
    "toc_title_is_page_title": True,
}

html_css_files = [
    'custom.css',
]

# Some special vodoo to render each rst-file by jinja, before it gets handled by Sphinx.
# This allows us to use the powerfull jinja-features to create content in a loop, react on
# external data input, or include templates with parameters.
# In our case we use it mostly to set the "demo page details" header in each page.
# A good blog post about this can be found here:
# Docs: https://ericholscher.com/blog/2016/jul/25/integrating-jinja-rst-sphinx/
def rstjinja(app, docname, source):
    """
    Render our pages as a jinja template for fancy templating goodness.

    This voodoo is needed as we use the jinja command ``include``, which searches
    for the referenced file. This works locally, but has't worked on ReadTheDocs.
    These more "complex" cwd and Template-Folder operations make it working.
    """
    old_cwd = os.getcwd()
    
    jinja2.FileSystemLoader(app.confdir)
    os.chdir(os.path.dirname(__file__))
    src = source[0]
    env = jinja2.Environment(loader=jinja2.FileSystemLoader('.'))
    template = env.from_string(src)
    #template = jinja2.Template(src, autoescape=True, environemnt=env)
    rendered = template.render(**app.config.html_context)
    source[0] = rendered
    os.chdir(old_cwd)

# This function allows us to register any kind of black magic for Sphinx :)
def setup(app):
    
    # We connect our jinja-function from above with the "source-read" event of Sphinx,
    # which gets called for every file before Sphinx starts to handle the file on its own.
    # This allows us to manipulate the content.
    app.connect("source-read", rstjinja)




###########################################################################
#          auto-created readthedocs.org specific configuration            #
###########################################################################


#
# The following code was added during an automated build on readthedocs.org
# It is auto created and injected for every build. The result is based on the
# conf.py.tmpl file found in the readthedocs.org codebase:
# https://github.com/rtfd/readthedocs.org/blob/main/readthedocs/doc_builder/templates/doc_builder/conf.py.tmpl
#
# Note: this file shouldn't rely on extra dependencies.

import importlib
import sys
import os.path

# Borrowed from six.
PY3 = sys.version_info[0] == 3
string_types = str if PY3 else basestring

from sphinx import version_info

# Get suffix for proper linking to GitHub
# This is deprecated in Sphinx 1.3+,
# as each page can have its own suffix
if globals().get('source_suffix', False):
    if isinstance(source_suffix, string_types):
        SUFFIX = source_suffix
    elif isinstance(source_suffix, (list, tuple)):
        # Sphinx >= 1.3 supports list/tuple to define multiple suffixes
        SUFFIX = source_suffix[0]
    elif isinstance(source_suffix, dict):
        # Sphinx >= 1.8 supports a mapping dictionary for multiple suffixes
        SUFFIX = list(source_suffix.keys())[0]  # make a ``list()`` for py2/py3 compatibility
    else:
        # default to .rst
        SUFFIX = '.rst'
else:
    SUFFIX = '.rst'

# Add RTD Static Path. Add to the end because it overwrites previous files.
if not 'html_static_path' in globals():
    html_static_path = []
if os.path.exists('_static'):
    html_static_path.append('_static')

# Define this variable in case it's not defined by the user.
# It defaults to `alabaster` which is the default from Sphinx.
# https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_theme
html_theme = globals().get('html_theme', 'alabaster')

#Add project information to the template context.
context = {
    'html_theme': html_theme,
    'current_version': "latest",
    'version_slug': "latest",
    'MEDIA_URL': "https://media.readthedocs.org/",
    'STATIC_URL': "https://assets.readthedocs.org/static/",
    'PRODUCTION_DOMAIN': "readthedocs.org",
    'proxied_static_path': "/_/static/",
    'versions': [
    ("latest", "/en/latest/"),
    ],
    'downloads': [ 
    ],
    'subprojects': [ 
    ],
    'slug': 'sphinx-needs-demo',
    'name': u'sphinx-needs-demo',
    'rtd_language': u'en',
    'programming_language': u'words',
    'canonical_url': '',
    'analytics_code': 'None',
    'single_version': False,
    'conf_py_path': '/docs/',
    'api_host': 'https://readthedocs.org',
    'github_user': 'useblocks',
    'proxied_api_host': '/_',
    'github_repo': 'sphinx-needs-demo',
    'github_version': 'main',
    'display_github': True,
    'bitbucket_user': 'None',
    'bitbucket_repo': 'None',
    'bitbucket_version': 'main',
    'display_bitbucket': False,
    'gitlab_user': 'None',
    'gitlab_repo': 'None',
    'gitlab_version': 'main',
    'display_gitlab': False,
    'READTHEDOCS': True,
    'using_theme': (html_theme == "default"),
    'new_theme': (html_theme == "sphinx_rtd_theme"),
    'source_suffix': SUFFIX,
    'ad_free': False,
    'docsearch_disabled': False,
    'user_analytics_code': '',
    'global_analytics_code': 'UA-17997319-1',
    'commit': '5f8ff1c2',
}

# For sphinx >=1.8 we can use html_baseurl to set the canonical URL.
# https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_baseurl
if version_info >= (1, 8):
    if not globals().get('html_baseurl'):
        html_baseurl = context['canonical_url']
    context['canonical_url'] = None





if 'html_context' in globals():
    for key in context:
        if key not in html_context:
            html_context[key] = context[key]
else:
    html_context = context

# Add custom RTD extension
if 'extensions' in globals():
    # Insert at the beginning because it can interfere
    # with other extensions.
    # See https://github.com/rtfd/readthedocs.org/pull/4054
    extensions.insert(0, "readthedocs_ext.readthedocs")
else:
    extensions = ["readthedocs_ext.readthedocs"]

# Add External version warning banner to the external version documentation
if 'branch' == 'external':
    extensions.insert(1, "readthedocs_ext.external_version_warning")
    readthedocs_vcs_url = 'None'
    readthedocs_build_url = 'https://readthedocs.org/projects/sphinx-needs-demo/builds/24828320/'

project_language = 'en'

# User's Sphinx configurations
language_user = globals().get('language', None)
latex_engine_user = globals().get('latex_engine', None)
latex_elements_user = globals().get('latex_elements', None)

# Remove this once xindy gets installed in Docker image and XINDYOPS
# env variable is supported
# https://github.com/rtfd/readthedocs-docker-images/pull/98
latex_use_xindy = False

chinese = any([
    language_user in ('zh_CN', 'zh_TW'),
    project_language in ('zh_CN', 'zh_TW'),
])

japanese = any([
    language_user == 'ja',
    project_language == 'ja',
])

if chinese:
    latex_engine = latex_engine_user or 'xelatex'

    latex_elements_rtd = {
        'preamble': '\\usepackage[UTF8]{ctex}\n',
    }
    latex_elements = latex_elements_user or latex_elements_rtd
elif japanese:
    latex_engine = latex_engine_user or 'platex'

# Make sure our build directory is always excluded
exclude_patterns = globals().get('exclude_patterns', [])
exclude_patterns.extend(['_build'])

Templates

req_post

Adds the “Object traceability details” under each requirement.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
.. if-builder:: html

   .. warning::
      :title: Object traceability details: {{title}}
      :collapsible:  

      .. needflow::
          :filter:  "{{id}}"==id or "{{id}}" in reqs or "{{id}}" in author_back

      .. needtable::
          :style: table
          :filter:  "{{id}}"==id or "{{id}}" in reqs or "{{id}}" in author_back
          :columns: id, title, type, author

spec_post

Adds the “Object traceability details” under each specification.

The used filters are slightly different from the ones used for requirements, therefore an extra template is used.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
.. if-builder:: html

   .. warning::
      :title: Object traceability details: {{title}}
      :collapsible:  

      .. needflow::
         :filter:  "{{id}}"==id or "{{id}}" in reqs_back or "{{id}}" in specs or "{{id}}" in author_back or "{{id}}" in implements

      .. needtable::
         :filter:  "{{id}}"==id or "{{id}}" in reqs_back or "{{id}}" in specs or "{{id}}" in author_back or "{{id}}" in implements
         :style: table
         :columns: id, title, type, author
         

Includes

demo_page_header

This is used to add the “Demo page details” on top of each page.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
.. if-builder:: html

   .. tip:: 
      :title: Demo page details
      :collapsible: 

      **Page source code: {{page}}** 

      .. literalinclude:: {{page}}
         :language: rst
         :linenos: