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.