diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml
index 9caef877f..42390fd39 100644
--- a/.github/workflows/docs.yaml
+++ b/.github/workflows/docs.yaml
@@ -6,8 +6,6 @@ jobs:
linkcheck:
name: Docs-Linkcheck
runs-on: ubuntu-20.04
- env:
- ON_CI: true
steps:
- uses: actions/checkout@v3.5.3
- name: Set Up Python
diff --git a/.github/workflows/js_test.yml b/.github/workflows/js_test.yml
index b0dd73154..3e0e6d23d 100644
--- a/.github/workflows/js_test.yml
+++ b/.github/workflows/js_test.yml
@@ -3,9 +3,6 @@ on: [pull_request]
jobs:
js_tests:
runs-on: ubuntu-latest
- env:
- ON_CI: true
- FAST_BUILD: true
steps:
- name: Set Up Python 3.10.8
uses: actions/setup-python@v4
diff --git a/Makefile b/Makefile
index af66bd23c..554dddd4c 100644
--- a/Makefile
+++ b/Makefile
@@ -36,6 +36,10 @@ docs-html:
docs-html-fast:
poetry run sphinx-build -j auto -b html docs/ docs/_build
+.PHONY: needs
+needs:
+ poetry run sphinx-build -a -E -j auto -b needs docs/ docs/_build
+
.PHONY: docs-pdf
docs-pdf:
poetry run make --directory docs/ clean && make --directory docs/ latexpdf
diff --git a/docs/_images/github_issue_1.png b/docs/_images/github_issue_1.png
new file mode 100644
index 000000000..99018c98e
Binary files /dev/null and b/docs/_images/github_issue_1.png differ
diff --git a/docs/_images/github_issue_2.png b/docs/_images/github_issue_2.png
new file mode 100644
index 000000000..9f5536440
Binary files /dev/null and b/docs/_images/github_issue_2.png differ
diff --git a/docs/_images/github_issue_3.png b/docs/_images/github_issue_3.png
new file mode 100644
index 000000000..2febfef93
Binary files /dev/null and b/docs/_images/github_issue_3.png differ
diff --git a/docs/_images/github_issue_4.png b/docs/_images/github_issue_4.png
new file mode 100644
index 000000000..1271157c9
Binary files /dev/null and b/docs/_images/github_issue_4.png differ
diff --git a/docs/_static/custom.css b/docs/_static/custom.css
index 1de3a1e16..828315217 100644
--- a/docs/_static/custom.css
+++ b/docs/_static/custom.css
@@ -181,4 +181,8 @@ div.dt-button-collection button.dt-button.active:not(.disabled) {
}
details.sd-dropdown .sd-summary-up, details.sd-dropdown .sd-summary-down {
display: none;
+}
+/* Image width fix in need-sidebars. */
+tbody div.needs_side img.needs_image {
+ max-width: 100px;
}
\ No newline at end of file
diff --git a/docs/conf.py b/docs/conf.py
index e2b89a8fc..06a1ddddc 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -58,6 +58,8 @@
"sphinx_immaterial",
]
+# smartquotes = False
+
needs_debug_measurement = True
add_module_names = False # Used to shorten function name output
@@ -128,6 +130,8 @@
# Absolute path to the needs_report_template_file based on the conf.py directory
# needs_report_template = "/needs_templates/report_template.need" # Use custom report template
+needs_report_dead_links = False
+
needs_types = [
# Architecture types
{
@@ -316,41 +320,7 @@
needs_service_all_data = True
-needs_services = {
- "github-issues": {
- "url": "https://api.github.com/",
- "max_content_lines": 20,
- "id_prefix": "GH_ISSUE_",
- },
- "github-prs": {
- "url": "https://api.github.com/",
- "max_content_lines": 20,
- "id_prefix": "GH_PR_",
- },
- "github-commits": {
- "url": "https://api.github.com/",
- "max_content_lines": 20,
- "id_prefix": "GH_COM_",
- },
- "open-needs": {
- "url": "http://127.0.0.1:9595",
- "user": os.environ.get("ONS_USERNAME", ""),
- "password": os.environ.get("ONS_PASSWORD", ""),
- "id_prefix": "ONS_",
- "mappings": {
- "id": "{{key}}",
- "type": ["type"],
- "title": "{{title}}",
- "status": ["options", "status"],
- "links": ["references", "links"],
- },
- "extra_data": {
- "Priority": ["options", "priority"],
- "Approval": ["options", "approved"],
- "Cost": ["options", "costs"],
- },
- },
-}
+needs_services = {}
needs_string_links = {
"config_link": {
@@ -392,19 +362,6 @@ def custom_defined_func():
needs_build_json = True
# build needs_json for every needs-id to make detail panel
needs_build_json_per_id = False
-# Get and maybe set GitHub credentials for services.
-# This is needed as the rate limit for not authenticated users is too low for the amount of requests we
-# need to perform for this documentation
-
-github_username = os.environ.get("GITHUB_USERNAME", "")
-github_token = os.environ.get("GITHUB_TOKEN", "")
-if github_username != "" and github_token != "":
- print(f"---> GITHUB: Using as username: {github_username}. length token: {len(github_token)}")
- for service in ["github-issues", "github-prs", "github-commits"]:
- needs_services[service]["username"] = github_username
- needs_services[service]["token"] = github_token
-else:
- print("---> GITHUB: No auth provided")
# Add any paths that contain templates here, relative to this directory.
templates_path = ["_templates"]
@@ -593,13 +550,7 @@ def custom_defined_func():
"""
-# Check, if docs get built on ci.
-# If this is the case, external services like Open-Needs are not available and
-# docs will show images instead of getting real data.
-on_ci = os.environ.get("ON_CI", "False").upper() == "TRUE"
-fast_build = os.environ.get("FAST_BUILD", "False").upper() == "TRUE"
-
-html_context = {"on_ci": on_ci, "fast_build": fast_build}
+html_context = {}
def rstjinja(app: Sphinx, _docname: str, source: List[str]) -> None:
@@ -618,8 +569,6 @@ def rstjinja(app: Sphinx, _docname: str, source: List[str]) -> None:
def setup(app: Sphinx) -> None:
- print(f"---> ON_CI is: {on_ci}")
- print(f"---> FAST_BUILD is: {fast_build}")
app.connect("source-read", rstjinja)
diff --git a/docs/configuration.rst b/docs/configuration.rst
index e4aa8db78..9d9ff8922 100644
--- a/docs/configuration.rst
+++ b/docs/configuration.rst
@@ -646,7 +646,7 @@ needs_report_template
.. versionadded:: 1.0.1
-You can customize the layout of :ref:`needreport` using `Jinja `_.
+You can customize the layout of :ref:`needreport` using `Jinja `__.
Set the value of ``needs_report_template`` to the path of the template you want to use.
@@ -2040,7 +2040,7 @@ needs_render_context
~~~~~~~~~~~~~~~~~~~~~
.. versionadded:: 1.0.3
-This option allows you to use custom data as context when rendering `Jinja `_ templates or strings.
+This option allows you to use custom data as context when rendering `Jinja `__ templates or strings.
Configuration example:
@@ -2134,7 +2134,7 @@ needs_template
*removed: 0.3.0*
-The layout of needs can be fully customized by using `jinja `_.
+The layout of needs can be fully customized by using `jinja `__.
If nothing is set, the following default template is used:
diff --git a/docs/directives/needuml.rst b/docs/directives/needuml.rst
index e49f6c8f8..7670839b3 100644
--- a/docs/directives/needuml.rst
+++ b/docs/directives/needuml.rst
@@ -111,7 +111,7 @@ Allows to inject additional key-value pairs into the ``needuml`` rendering.
It is not available in code loaded via :ref:`needuml_jinja_uml`.
So we suggest to use them only in non-embedded needuml directives.
In an embedded needuml, you can store the information in the options
- of the need and access them with :ref:`needflow_need` like in
+ of the need and access them with :ref:`needflow` like in
:ref:`needuml` introduction.
diff --git a/docs/layout_styles.rst b/docs/layout_styles.rst
index 9106a202f..61fb39b3a 100644
--- a/docs/layout_styles.rst
+++ b/docs/layout_styles.rst
@@ -371,11 +371,11 @@ Available layout functions are:
.. autofunction:: sphinx_needs.layout.LayoutHandler.meta_links_all(prefix='', postfix='', exclude=None)
-.. autofunction:: sphinx_needs.layout.LayoutHandler.image(url, height=None, width=None, align=None, no_link=False)
+.. autofunction:: sphinx_needs.layout.LayoutHandler.image(url, height=None, width=None, align=None, no_link=False, prefix="", is_external=False, img_class="")
-.. autofunction:: sphinx_needs.layout.LayoutHandler.link(url, text=None, image_url=None, image_height=None, image_width=None)
+.. autofunction:: sphinx_needs.layout.LayoutHandler.link(url, text=None, image_url=None, image_height=None, image_width=None, prefix="", is_dynamic=False)
-.. autofunction:: sphinx_needs.layout.LayoutHandler.permalink(image_url=None, image_height=None, image_width=None, text=None)
+.. autofunction:: sphinx_needs.layout.LayoutHandler.permalink(image_url=None, image_height=None, image_width=None, text=None, prefix="")
.. autofunction:: sphinx_needs.layout.LayoutHandler.collapse_button(target='meta', collapsed='Show', visible='Close', initial=False)
diff --git a/docs/performance/index.rst b/docs/performance/index.rst
index bb8f9014e..178e37d1f 100644
--- a/docs/performance/index.rst
+++ b/docs/performance/index.rst
@@ -7,4 +7,5 @@ Performance & Profiling
:maxdepth: 2
script
+ debug
diff --git a/docs/performance/script.rst b/docs/performance/script.rst
index a9c9c9f0e..e2587aaca 100644
--- a/docs/performance/script.rst
+++ b/docs/performance/script.rst
@@ -1,4 +1,4 @@
-.. _performance:
+.. _performance_script:
Performance & Profiling script
==============================
diff --git a/docs/services/github.rst b/docs/services/github.rst
index 515a48125..e72605722 100644
--- a/docs/services/github.rst
+++ b/docs/services/github.rst
@@ -22,14 +22,13 @@ Each services creates normally multiple need objects for each element found by q
.. needservice:: github-issues
:query: repo:useblocks/sphinx-needs node latexpdf
+ :max_amount: 1
:max_content_lines: 4
-{% if fast_build != true %}
-.. needservice:: github-issues
- :query: repo:useblocks/sphinx-needs node latexpdf
- :max_amount: 1
- :max_content_lines: 4
-{% endif %}
+.. figure:: /_images/github_issue_1.png
+ :scale: 80%
+
+ Example of a github Issue collected with Sphinx-Needs.
Directive options, which can also used for normal needs, can also be set for ``needservice`` directive.
Also the content part of ``needservice`` is added as extra data to the end of the finally created needs.
@@ -51,20 +50,10 @@ Also the content part of ``needservice`` is added as extra data to the end of th
Extra content for each new need
-{% if fast_build != true %}
-.. needservice:: github-issues
- :type: spec
- :author: Me
- :tags: awesome, issue
- :query: repo:useblocks/sphinx-needs node latexpdf
- :id_prefix: GH_
- :max_amount: 1
- :max_content_lines: 4
- :layout: clean
- :style: discreet
-
- Extra content for each new need
-{%endif%}
+.. figure:: /_images/github_issue_2.png
+ :scale: 80%
+
+ Example of a github Issue collected with Sphinx-Needs.
Querying objects
----------------
@@ -101,10 +90,6 @@ This loads all open issues, which have the strings *needtable* and *viewports* i
.. needservice:: github-issues
:query: repo:useblocks/sphinx-needs state:open needtable viewports
-{% if fast_build != true %}
-.. needservice:: github-issues
- :query: repo:useblocks/sphinx-needs state:open needtable viewports
-{%endif%}
specific
++++++++
@@ -123,10 +108,10 @@ This query fetches a specific pull request with the id 161.
.. needservice:: github-prs
:specific: useblocks/sphinx-needs/161
-{% if fast_build != true %}
-.. needservice:: github-prs
- :specific: useblocks/sphinx-needs/161
-{%endif%}
+.. figure:: /_images/github_issue_3.png
+ :scale: 80%
+
+ Example of a github Issue collected with Sphinx-Needs.
.. _service_github_config:
@@ -193,15 +178,10 @@ directive :ref:`needservice`.
:layout: focus_l
:style: blue_border
-{% if fast_build != true %}
-.. needservice:: github-issues
- :query: repo:useblocks/sphinx-needs node latexpdf
- :max_amount: 1
- :max_content_lines: 4
- :id_prefix: GH2_
- :layout: focus_l
- :style: blue_border
-{%endif%}
+.. figure:: /_images/github_issue_4.png
+ :scale: 80%
+
+ Example of a github Issue collected with Sphinx-Needs.
Need type
+++++++++
@@ -273,10 +253,6 @@ Search for all commits of Sphinx-Needs, which have ``Python`` in their message.
:query: repo:useblocks/sphinx-needs python
:max_amount: 2
-.. needservice:: github-commits
- :query: repo:useblocks/sphinx-needs python
- :max_amount: 2
-
**Specific commit**
Document commit ``a4a596`` of **Sphinx-Needs**.
@@ -286,8 +262,6 @@ Document commit ``a4a596`` of **Sphinx-Needs**.
.. needservice:: github-commits
:specific: useblocks/sphinx-needs/a4a596
-.. needservice:: github-commits
- :specific: useblocks/sphinx-needs/a4a596113
Filtering
+++++++++
diff --git a/docs/services/open_needs.rst b/docs/services/open_needs.rst
index 55663ce61..5b5f72979 100644
--- a/docs/services/open_needs.rst
+++ b/docs/services/open_needs.rst
@@ -216,22 +216,9 @@ Examples
**Result**
-{% if on_ci != true %}
-
-.. needservice:: open-needs
- :prefix: ONS_
- :params: skip=0;limit=10
-
-.. needtable::
- :filter: "ONS" in id
- :columns: id, title, status, type
- :style: table
-
-{% else %}
.. hint::
The below examples are just images, as no Open-Needs Server instance was available during documentation build.
- In order for this to work, you must set the ``ON_CI`` environment variable to ``True``
.. image:: /_images/ons_example.png
:align: center
@@ -239,6 +226,4 @@ Examples
.. image:: /_images/ons_table.png
:align: center
- :width: 60%
-
-{% endif %}
\ No newline at end of file
+ :width: 60%
\ No newline at end of file
diff --git a/noxfile.py b/noxfile.py
index 0310406d5..85f54d0cb 100644
--- a/noxfile.py
+++ b/noxfile.py
@@ -77,7 +77,6 @@ def benchmark_time(session):
"--benchmark-json",
"output.json",
external=True,
- env={"ON_CI": "true", "FAST_BUILD": "true"},
)
@@ -94,7 +93,6 @@ def benchmark_memory(session):
"--benchmark-json",
"output.json",
external=True,
- env={"ON_CI": "true", "FAST_BUILD": "true"},
)
session.run("memray", "flamegraph", "-o", "mem_out.html", "mem_out.bin")
diff --git a/sphinx_needs/functions/common.py b/sphinx_needs/functions/common.py
index 230eb339a..a256834a6 100644
--- a/sphinx_needs/functions/common.py
+++ b/sphinx_needs/functions/common.py
@@ -112,7 +112,7 @@ def copy(app: Sphinx, need, needs, option, need_id=None, lower: bool = False, up
.. test:: test of current_need value
:id: copy_4
- The following copy command copies the title of the first need found under the same highest
+ The es the title of the first need found under the same highest
section (headline):
[[copy('title', filter='current_need["sections"][-1]==sections[-1]')]]
diff --git a/tests/benchmarks/test_official.py b/tests/benchmarks/test_official.py
index ce2b47a45..b2f3ba6a8 100644
--- a/tests/benchmarks/test_official.py
+++ b/tests/benchmarks/test_official.py
@@ -1,4 +1,3 @@
-import os
import re
from pathlib import Path
@@ -20,9 +19,6 @@ def test_official_time(test_app, benchmark):
)
responses.add(responses.GET, re.compile(r"https://avatars.githubusercontent.com/.*"), body="")
- os.environ["ON_CI"] = "true"
- os.environ["FAST_BUILD"] = "true"
-
app = test_app
benchmark.pedantic(app.builder.build_all, rounds=1, iterations=1)
@@ -43,9 +39,6 @@ def test_official_memory(test_app):
)
responses.add(responses.GET, re.compile(r"https://avatars.githubusercontent.com/.*"), body="")
- os.environ["ON_CI"] = "true"
- os.environ["FAST_BUILD"] = "true"
-
app = test_app
# Okay, that's really ugly.