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

Update docs with confval definitions #714

Open
fmigneault opened this issue Sep 14, 2024 · 0 comments
Open

Update docs with confval definitions #714

fmigneault opened this issue Sep 14, 2024 · 0 comments
Assignees
Labels
ci/doc Issue related to documentation of the package triage/enhancement New feature or request

Comments

@fmigneault
Copy link
Collaborator

fmigneault commented Sep 14, 2024

Description

Currently, configuration settings are defined using custom definitions. For example:

- | ``weaver.wps = true|false`` [:class:`bool`-like]
| (default: ``true``)
|
| Enables the WPS-1/2 endpoint.
.. seealso::
:ref:`wps_endpoint`
.. warning::
At the moment, this setting must be ``true`` to allow :term:`Job` execution as the worker monitors this endpoint.
This could change with future developments (see issue `#21 <https://github.com/crim-ca/weaver/issues/21>`_).

Sphinx provides a way to define confval directives, which can be referenced by :confval:`<ref>`.
This can be used to fix current workarounds using :ref: or `<ref>`_ references pointing at custom anchors before those settings, while providing nicer rendering.

Using confval allows to directly making use of the directive to define :type: and :default::

.. confval:: the_answer
   :type: ``int`` (a *number*)
   :default: **42**

   This is a setting that controls the value of the answer.

Which would be rendered as:


the_answer
Type:
int (a number)
Default:
42

This is a setting that controls the value of the answer.


References

@fmigneault fmigneault added the triage/feature New requested feature. label Sep 14, 2024
@fmigneault fmigneault self-assigned this Sep 14, 2024
@fmigneault fmigneault added triage/enhancement New feature or request ci/doc Issue related to documentation of the package and removed triage/feature New requested feature. labels Sep 14, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
ci/doc Issue related to documentation of the package triage/enhancement New feature or request
Projects
None yet
Development

No branches or pull requests

1 participant