Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

✨ NEW: Add NeedsPerPageBuilder #962

Open
wants to merge 39 commits into
base: master
Choose a base branch
from
Open

✨ NEW: Add NeedsPerPageBuilder #962

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
39 commits
Select commit Hold shift + click to select a range
da212be
create build for need-per-page
nhatnamnguyengtvthcm Jul 14, 2023
41b240c
create build for need-per-page
nhatnamnguyengtvthcm Jul 14, 2023
7292694
create build for need-per-page
nhatnamnguyengtvthcm Jul 14, 2023
b175483
create build for need-per-page
nhatnamnguyengtvthcm Jul 14, 2023
364bcae
update logic write file need json per page
nhatnamnguyengtvthcm Jul 21, 2023
59e1b57
add configuration for need per page
nhatnamnguyengtvthcm Jul 21, 2023
fffd402
Removed esbonio for IDE support
haiyangToAI Feb 17, 2023
9054ef7
enable docker arm builds
cpolzer May 31, 2023
8277dce
🔧 Add .nox to gitignore
chrisjsewell Aug 2, 2023
406f02f
Update pyproject.toml
chrisjsewell Aug 3, 2023
296cbbd
Update pyproject.toml
chrisjsewell Aug 3, 2023
7d322c6
Update requirements.txt
chrisjsewell Aug 3, 2023
240c0ab
Update api.rst
chrisjsewell Aug 3, 2023
d336da8
Added config allow unsafe filter for filter_func (#949)
haiyangToAI Aug 3, 2023
d1f2c1b
🔧 Update pre-commit hooks (#956)
chrisjsewell Aug 4, 2023
65e60a7
Bump actions/checkout from 3.3.0 to 3.5.3
dependabot[bot] Jun 12, 2023
4fc8171
needs: Remove some of the extra IDs in the output
tim-nordell-nimbelink Nov 21, 2022
bfb355c
Added config option needs_report_dead_links (#937)
haiyangToAI Aug 4, 2023
5f6bc5d
Raises version to 1.3.0
danwos Aug 16, 2023
8d978fa
👌 Performance: Memoize Inline Parser
chrisjsewell Aug 11, 2023
b66b99c
fix linting
chrisjsewell Aug 16, 2023
725d98f
Add to changelog
chrisjsewell Aug 16, 2023
95ea444
fix merge version 1.3.0
nhatnamnguyengtvthcm Aug 22, 2023
0a17349
Docker fix
danwos Aug 18, 2023
25c28c1
Removing docker context: ci
danwos Aug 18, 2023
b5b7a3d
♻️ Change `NeedsBuilder` format to `needs`
chrisjsewell Aug 21, 2023
76b7442
Update changelog.rst
chrisjsewell Aug 21, 2023
bbc58df
create build for need-per-page
nhatnamnguyengtvthcm Jul 14, 2023
9b514f1
create build for need-per-page
nhatnamnguyengtvthcm Jul 14, 2023
e63e52a
create build for need-per-page
nhatnamnguyengtvthcm Jul 14, 2023
1c192e0
update logic write file need json per page
nhatnamnguyengtvthcm Jul 21, 2023
56c027b
fix merge version 1.3.0
nhatnamnguyengtvthcm Aug 22, 2023
8332508
add testcase and changelog.rst and configurations.rst
nhatnamnguyengtvthcm Aug 23, 2023
41026f4
add testcase and changelog.rst and configurations.rst
nhatnamnguyengtvthcm Aug 23, 2023
6201bfd
add testcase and changelog.rst and configurations.rst
nhatnamnguyengtvthcm Aug 23, 2023
5770983
add testcase and changelog.rst and configurations.rst
nhatnamnguyengtvthcm Aug 23, 2023
370b026
add testcase and changelog.rst and configurations.rst
nhatnamnguyengtvthcm Aug 23, 2023
95653f4
add testcase and changelog.rst and configurations.rst
nhatnamnguyengtvthcm Aug 23, 2023
4a67fae
update builder and document
nhatnamnguyengtvthcm Aug 24, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
230 changes: 230 additions & 0 deletions docs/builders.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -163,3 +163,233 @@ or
.. hint::

As an alternative, you can set the config option :ref:`needs_build_needumls` to export the needumls files during each build.

.. _needs_per_page_builder:

needs_per_page
--------------
.. versionadded:: 1.4.0

The **needs_per_page** builder exports all found needs with same ``docname`` into separate ``json`` file.
If docname has slash like ``directives/list2need``, the file will be located in folder called :ref:`needs_per_page_build_path`.
e.g. `needs_per_page/directives/list2need.json` .

Usage
+++++


.. code-block:: bash

sphinx-build -b needs_per_page source_dir build_dir


Format
++++++
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What does this syntax do?

Please build the docs and check for errors before submitting.
A make docs-html is now enough, as I fixed the doc-build and made it much easier.

.. code-block:: python
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you move this to a json file and present it here via .. literalinclude::?
Much easier to maintain.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe just remove this and use the testing snapshots.
The problem with having it "statically" in the documentation, is that it is prone to become out-of-date with the actual code


{
"needs": [
{
"xyz_123": {
"docname": "configuration",
"doctype": ".rst",
"lineno": 203,
"target_id": "xyz_123",
"external_url": null,
"content_id": "xyz_123",
"type": "req",
"type_name": "Requirement",
"type_prefix": "R_",
"type_color": "#BFD8D2",
"type_style": "node",
"status": "open",
"tags": [],
"constraints": [],
"constraints_passed": null,
"constraints_results": {},
"id": "xyz_123",
"title": "My requirement with custom options",
"full_title": "My requirement with custom options",
"content": "Some content",
"collapse": null,
"arch": {},
"style": null,
"layout": "",
"template": null,
"pre_template": null,
"post_template": null,
"hide": false,
"delete": null,
"jinja_content": null,
"parts": {},
"is_part": false,
"is_need": true,
"is_external": false,
"external_css": "external_link",
"is_modified": false,
"modifications": 0,
"my_extra_option": "A new option",
"another_option": "filter_me",
"author": "",
"comment": "",
"amount": "",
"hours": "",
"image": "",
"config": "",
"github": "",
"value": "",
"unit": "",
"query": "",
"specific": "",
"max_amount": "",
"max_content_lines": "",
"id_prefix": "",
"user": "",
"created_at": "",
"updated_at": "",
"closed_at": "",
"service": "",
"url": "",
"avatar": "",
"params": "",
"prefix": "",
"url_postfix": "",
"hidden": "",
"duration": "",
"completion": "",
"has_dead_links": "",
"has_forbidden_dead_links": "",
"links": [],
"links_back": [],
"parent_needs": [],
"parent_needs_back": [],
"blocks": [],
"blocks_back": [],
"tests": [],
"tests_back": [],
"checks": [],
"checks_back": [],
"triggers": [],
"triggers_back": [],
"starts_with": [],
"starts_with_back": [],
"starts_after": [],
"starts_after_back": [],
"ends_with": [],
"ends_with_back": [],
"sections": [
"needs_extra_options",
"Options",
"Configuration"
],
"section_name": "needs_extra_options",
"signature": "",
"parent_need": "",
"id_parent": "xyz_123",
"id_complete": "xyz_123"
}
},
{
"EXTRA_REQ_001": {
"docname": "configuration",
"doctype": ".rst",
"lineno": 371,
"target_id": "EXTRA_REQ_001",
"external_url": null,
"content_id": "EXTRA_REQ_001",
"type": "req",
"type_name": "Requirement",
"type_prefix": "R_",
"type_color": "#BFD8D2",
"type_style": "node",
"status": null,
"tags": [],
"constraints": [],
"constraints_passed": null,
"constraints_results": {},
"id": "EXTRA_REQ_001",
"title": "My requirement",
"full_title": "My requirement",
"content": "",
"collapse": null,
"arch": {},
"style": null,
"layout": "",
"template": null,
"pre_template": null,
"post_template": null,
"hide": false,
"delete": null,
"jinja_content": null,
"parts": {},
"is_part": false,
"is_need": true,
"is_external": false,
"external_css": "external_link",
"is_modified": false,
"modifications": 0,
"my_extra_option": "",
"another_option": "",
"author": "",
"comment": "",
"amount": "",
"hours": "",
"image": "",
"config": "",
"github": "",
"value": "",
"unit": "",
"query": "",
"specific": "",
"max_amount": "",
"max_content_lines": "",
"id_prefix": "",
"user": "",
"created_at": "",
"updated_at": "",
"closed_at": "",
"service": "",
"url": "",
"avatar": "",
"params": "",
"prefix": "",
"url_postfix": "",
"hidden": "",
"duration": "",
"completion": "",
"has_dead_links": "",
"has_forbidden_dead_links": "",
"links": [],
"links_back": [],
"parent_needs": [],
"parent_needs_back": [],
"blocks": [],
"blocks_back": [],
"tests": [],
"tests_back": [],
"checks": [],
"checks_back": [
"EXTRA_TEST_001"
],
"triggers": [],
"triggers_back": [],
"starts_with": [],
"starts_with_back": [],
"starts_after": [],
"starts_after_back": [],
"ends_with": [],
"ends_with_back": [],
"sections": [
"needs_extra_links",
"Options",
"Configuration"
],
"section_name": "needs_extra_links",
"signature": "",
"parent_need": "",
"id_parent": "EXTRA_REQ_001",
"id_complete": "EXTRA_REQ_001"
}
}
]
}
2 changes: 2 additions & 0 deletions docs/changelog.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,8 @@ Released: under development
-----
Released: under development

* Improvement: Added Builder :ref:`needs_per_page_builder:` added and config option :ref:`needs_per_page_build_path`

* Improvement: Reduce document build time, by memoizing the inline parse in ``build_need`` (`#968 <https://github.com/useblocks/sphinx-needs/pull/968>`_)

* Change `NeedsBuilder` format to `needs` (`#978 <https://github.com/useblocks/sphinx-needs/pull/978>`_)
Expand Down
3 changes: 3 additions & 0 deletions docs/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -361,6 +361,9 @@ def custom_defined_func():
# build needs.json to make permalinks work
needs_build_json = True

# build json file include needs with the same docs_name
needs_per_page = True
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This option name should be consistent with the other builders (build_json, build_json_per_id), i.e. build_json_per_page

Thinking holistically, with there now being numerous data writers, and more on the way, maybe it makes sense to have some form of unified configuration option.

For example:

needs_data_writers = ["json", "json_per_id", "json_per_page"]


# Add any paths that contain templates here, relative to this directory.
templates_path = ["_templates"]

Expand Down
31 changes: 31 additions & 0 deletions docs/configuration.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2289,3 +2289,34 @@ If true, need options like status, tags or links are collapsed and shown only af
Default value: True

Can be overwritten for each single need by setting :ref:`need_collapse`.


.. _needs_per_page:

needs_per_page
~~~~~~~~~~~~~~

.. versionadded:: 1.4.0

Build list of ``json`` files that contain all found needs with the same ``docname``. The name of each file should match the ``docname``.

This option works like :ref:`needs_build_json`.

Default: False


.. _needs_per_page_build_path:

needs_per_page_build_path
~~~~~~~~~~~~~~~~~~~~~~~~~

.. versionadded:: 1.4.0

This option sets the location of list of ``json`` files that contain all found needs with the same ``docname``.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this a folder or a file name?
Is it relative to the build folder or to the documentation root?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It is name of folder


Default value: need_per_page
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please highlight path information like need_per_page.
Add also a / if it is a folder



.. hint::

The created ``need_per_page`` folder gets stored in the ``outdir`` of the current builder folder. This is e.g `_build/needs_per_page/directives/list2need.json`
Loading