Clean up built-in xtrigger docstrings #5840
Conversation
| >>> xrandom(0, 0) | ||
| (False, {}) | ||
|
|
||
| .. code-block:: python |
There was a problem hiding this comment.
We shouldn't have to do this.
The Napoleon extension should automatically interpret the examples section as a Python code-block.
There was a problem hiding this comment.
But we aren't using Napoleon in cylc-doc, only Rose.
Suggest adding this into the extension list in cylc-doc:
'sphinx.ext.napoleon'
It's a built-in plugin, but it's not enabled by default, it understands the stricture of Google style docstring (what we use) and formats them more nicely, e.g:
There was a problem hiding this comment.
Unfortunately it seems to be choking on non-built-in exceptions in "Raises" sections of doctrings.
cylc/flow/network/client.py:docstring of cylc.flow.network.client.WorkflowRuntimeClient:1: WARNING: py:exc reference target not found: WorkflowStopped
cylc/flow/network/client.py:docstring of cylc.flow.network.client.WorkflowRuntimeClientBase.serial_request:1: WARNING: py:exc reference target not found: ClientTimeout
cylc/flow/network/client.py:docstring of cylc.flow.network.client.WorkflowRuntimeClientBase.serial_request:1: WARNING: py:exc reference target not found: ClientError
cylc/flow/jinja/filters/strftime.py:docstring of cylc.flow.jinja.filters.strftime.strftime:1: WARNING: py:exc reference target not found: ISO8601SyntaxError
cylc/flow/jinja/filters/strftime.py:docstring of cylc.flow.jinja.filters.strftime.strftime:1: WARNING: py:exc reference target not found: StrftimeSyntaxError
cylc/flow/jinja/filters/duration_as.py:docstring of cylc.flow.jinja.filters.duration_as.duration_as:1: WARNING: py:exc reference target not found: ISO8601SyntaxError
Doing this doesn't work:
Raises:
- WorkflowStopped: ...
+ cylc.flow.exceptions.WorkflowStopped: ...There was a problem hiding this comment.
I think py:exc reference target not found means that it is trying to cross-reference the exception, but can't because the exception hasn't been documented.
Normally this wouldn't matter, but we turn on nit-picky mode so that referencing errors cause failures.
One option would be to auto-document exceptions in the reference section. I guess this could have some value.
There was a problem hiding this comment.
[unrelated] Skimming the Rose config I spotted we're using sphinx.ext.viewcode there which is kinda cool.
|
Superseded by #5955 |
Accompanies but does not depend on cylc/cylc-doc#673
Check List
CONTRIBUTING.mdand added my name as a Code Contributor.?.?.xbranch.