Skip to content

Commit

Permalink
Easier Sphinx-Needs docs builds
Browse files Browse the repository at this point in the history
* Removes needservice dependency to external services like github
* Shows images instead of real fetch external data
* Removes on_ci and fast_build ENV vars and logic
* Adds "make needs" command to get a needs.json file
  • Loading branch information
danwos authored and nhatnamnguyengtvthcm committed Aug 21, 2023
1 parent ceae80e commit 4ee996e
Show file tree
Hide file tree
Showing 19 changed files with 42 additions and 139 deletions.
2 changes: 0 additions & 2 deletions .github/workflows/docs.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,6 @@ jobs:
linkcheck:
name: Docs-Linkcheck
runs-on: ubuntu-20.04
env:
ON_CI: true
steps:
- uses: actions/[email protected]
- name: Set Up Python
Expand Down
3 changes: 0 additions & 3 deletions .github/workflows/js_test.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 4 additions & 0 deletions Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Binary file added docs/_images/github_issue_1.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/_images/github_issue_2.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/_images/github_issue_3.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/_images/github_issue_4.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
4 changes: 4 additions & 0 deletions docs/_static/custom.css
Original file line number Diff line number Diff line change
Expand Up @@ -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;
}
63 changes: 6 additions & 57 deletions docs/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -58,6 +58,8 @@
"sphinx_immaterial",
]

# smartquotes = False

needs_debug_measurement = True

add_module_names = False # Used to shorten function name output
Expand Down Expand Up @@ -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
{
Expand Down Expand Up @@ -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": {
Expand Down Expand Up @@ -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"]
Expand Down Expand Up @@ -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:
Expand All @@ -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)


Expand Down
6 changes: 3 additions & 3 deletions docs/configuration.rst
Original file line number Diff line number Diff line change
Expand Up @@ -646,7 +646,7 @@ needs_report_template
.. versionadded:: 1.0.1
You can customize the layout of :ref:`needreport` using `Jinja <http://jinja.pocoo.org/>`_.
You can customize the layout of :ref:`needreport` using `Jinja <http://jinja.pocoo.org/>`__.
Set the value of ``needs_report_template`` to the path of the template you want to use.
Expand Down Expand Up @@ -2040,7 +2040,7 @@ needs_render_context
~~~~~~~~~~~~~~~~~~~~~
.. versionadded:: 1.0.3
This option allows you to use custom data as context when rendering `Jinja <https://jinja.palletsprojects.com/>`_ templates or strings.
This option allows you to use custom data as context when rendering `Jinja <https://jinja.palletsprojects.com/>`__ templates or strings.
Configuration example:
Expand Down Expand Up @@ -2134,7 +2134,7 @@ needs_template
*removed: 0.3.0*
The layout of needs can be fully customized by using `jinja <http://jinja.pocoo.org/>`_.
The layout of needs can be fully customized by using `jinja <http://jinja.pocoo.org/>`__.
If nothing is set, the following default template is used:
Expand Down
2 changes: 1 addition & 1 deletion docs/directives/needuml.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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.


Expand Down
6 changes: 3 additions & 3 deletions docs/layout_styles.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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)

Expand Down
1 change: 1 addition & 0 deletions docs/performance/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -7,4 +7,5 @@ Performance & Profiling
:maxdepth: 2

script
debug

2 changes: 1 addition & 1 deletion docs/performance/script.rst
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
.. _performance:
.. _performance_script:

Performance & Profiling script
==============================
Expand Down
60 changes: 17 additions & 43 deletions docs/services/github.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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
----------------
Expand Down Expand Up @@ -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
++++++++
Expand All @@ -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:

Expand Down Expand Up @@ -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
+++++++++
Expand Down Expand Up @@ -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**.
Expand All @@ -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
+++++++++
Expand Down
17 changes: 1 addition & 16 deletions docs/services/open_needs.rst
Original file line number Diff line number Diff line change
Expand Up @@ -216,29 +216,14 @@ 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
:width: 60%

.. image:: /_images/ons_table.png
:align: center
:width: 60%

{% endif %}
:width: 60%
2 changes: 0 additions & 2 deletions noxfile.py
Original file line number Diff line number Diff line change
Expand Up @@ -77,7 +77,6 @@ def benchmark_time(session):
"--benchmark-json",
"output.json",
external=True,
env={"ON_CI": "true", "FAST_BUILD": "true"},
)


Expand All @@ -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")

Expand Down
2 changes: 1 addition & 1 deletion sphinx_needs/functions/common.py
Original file line number Diff line number Diff line change
Expand Up @@ -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]')]]
Expand Down
Loading

0 comments on commit 4ee996e

Please sign in to comment.