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.

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

✨ Add needs_from_toml configuration #1337

Merged
merged 10 commits into from
Oct 27, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
386 changes: 4 additions & 382 deletions docs/conf.py

Large diffs are not rendered by default.

45 changes: 44 additions & 1 deletion docs/configuration.rst
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
Configuration
=============

All configurations take place in your project's **conf.py** file.
All root configurations take place in your project's :external+sphinx:ref:`conf.py file <build-config>`.

Activation
----------
Expand All @@ -14,6 +14,13 @@ Add **sphinx_needs** to your extensions.

extensions = ["sphinx_needs",]

Available sphinx-needs options are then listed below, that can be added to your **conf.py** file.

.. versionadded:: 4.1.0

Configuration can also be specified via a `toml file <https://toml.io>`__.
See :ref:`needs_from_toml` for more details.

.. _config-warnings:

Build Warnings
Expand Down Expand Up @@ -79,6 +86,42 @@ Options

All configuration options starts with the prefix ``needs_`` for **Sphinx-Needs**.

.. _needs_from_toml:

needs_from_toml
~~~~~~~~~~~~~~~

.. versionadded:: 4.1.0

This configuration takes the (relative) path to a `toml file <https://toml.io>`__ which contains some or all of the needs configuration (configuration in the toml will override that in the :file:`conf.py`).

.. code-block:: python

needs_from_toml = "ubproject.toml"

Configuration in the toml can contain any of the options below, under a ``[needs]`` section,
but with the ``needs_`` prefix removed.
For example:

.. code-block:: toml

[needs]
id_required = true
id_length = 3
types = [
{directive="req", title="Requirement", prefix="R_", color="#BFD8D2", style="node"},
{directive="spec", title="Specification", prefix="S_", color="#FEDCD2", style="node"},
]

To specify a different `table path <https://toml.io/en/v1.0.0#table>`__ to read from in the toml file, use the ``needs_from_toml_table`` option.
For example to read from a ``[tool.needs]`` table:

.. code-block:: python

needs_from_toml_table = ["tool", "needs"]

.. caution:: Any configuration specifying relative paths in the toml file will be resolved relative to the directory containing the :file:`conf.py` file.

needs_include_needs
~~~~~~~~~~~~~~~~~~~
Set this option to False, if no needs should be documented inside the generated documentation.
Expand Down
2 changes: 1 addition & 1 deletion docs/contributing.rst
Original file line number Diff line number Diff line change
Expand Up @@ -117,7 +117,7 @@ Running JS Testcases with PyTest
**Setup Cypress Locally**

* Install Node JS on your computer and ensure it can be accessed through the CMD.
* Install Cypress using the npm package manager by running ``npm install cypress``. Visit this link for more information on `how to install Cypress <https://docs.cypress.io/guides/getting-started/installing-cypress#npm-install>`_.
* Install Cypress using the npm package manager by running ``npm install cypress``. Visit this link for more information on `how to install Cypress <https://docs.cypress.io/guides/getting-started/installing-cypress>`_.
* Verify if Cypress is installed correctly and is executable by running: ``npx cypress verify``. Get out this page for more information about `Cypress commandline <https://docs.cypress.io/guides/guides/command-line>`_.
* If everything is successful then we can use Cypress.

Expand Down
Loading
Loading