[v16,1/5] dts: update params and parser docstrings
Checks
Commit Message
Address a few errors reported by Sphinx when generating documentation:
framework/params/__init__.py:docstring of framework.params.modify_str:3:
WARNING: Inline interpreted text or phrase reference start-string
without end-string.
framework/params/eal.py:docstring of framework.params.eal.EalParams:35:
WARNING: Definition list ends without a blank line; unexpected
unindent.
framework/params/types.py:docstring of framework.params.types:8:
WARNING: Inline strong start-string without end-string.
framework/params/types.py:docstring of framework.params.types:9:
WARNING: Inline strong start-string without end-string.
framework/parser.py:docstring of framework.parser.TextParser:33: ERROR:
Unexpected indentation.
framework/parser.py:docstring of framework.parser.TextParser:43: ERROR:
Unexpected indentation.
framework/parser.py:docstring of framework.parser.TextParser:49: ERROR:
Unexpected indentation.
framework/parser.py:docstring of framework.parser.TextParser.wrap:8:
ERROR: Unexpected indentation.
framework/parser.py:docstring of framework.parser.TextParser.wrap:9:
WARNING: Block quote ends without a blank line; unexpected unindent.
Fixes: 87ba4cdc0dbb ("dts: use Unpack for type checking and hinting")
Fixes: d70159cb62f5 ("dts: add params manipulation module")
Fixes: 967fc62b0a43 ("dts: refactor EAL parameters class")
Fixes: 818fe14e3422 ("dts: add parsing utility module")
Cc: luca.vizzarro@arm.com
Signed-off-by: Juraj Linkeš <juraj.linkes@pantheon.tech>
Reviewed-by: Luca Vizzarro <luca.vizzarro@arm.com>
---
dts/framework/params/__init__.py | 4 ++--
dts/framework/params/eal.py | 7 +++++--
dts/framework/params/types.py | 3 ++-
dts/framework/parser.py | 4 ++--
4 files changed, 11 insertions(+), 7 deletions(-)
Comments
On Thu, Aug 8, 2024 at 4:54 AM Juraj Linkeš <juraj.linkes@pantheon.tech> wrote:
>
> Address a few errors reported by Sphinx when generating documentation:
> framework/params/__init__.py:docstring of framework.params.modify_str:3:
> WARNING: Inline interpreted text or phrase reference start-string
> without end-string.
> framework/params/eal.py:docstring of framework.params.eal.EalParams:35:
> WARNING: Definition list ends without a blank line; unexpected
> unindent.
> framework/params/types.py:docstring of framework.params.types:8:
> WARNING: Inline strong start-string without end-string.
> framework/params/types.py:docstring of framework.params.types:9:
> WARNING: Inline strong start-string without end-string.
> framework/parser.py:docstring of framework.parser.TextParser:33: ERROR:
> Unexpected indentation.
> framework/parser.py:docstring of framework.parser.TextParser:43: ERROR:
> Unexpected indentation.
> framework/parser.py:docstring of framework.parser.TextParser:49: ERROR:
> Unexpected indentation.
> framework/parser.py:docstring of framework.parser.TextParser.wrap:8:
> ERROR: Unexpected indentation.
> framework/parser.py:docstring of framework.parser.TextParser.wrap:9:
> WARNING: Block quote ends without a blank line; unexpected unindent.
>
> Fixes: 87ba4cdc0dbb ("dts: use Unpack for type checking and hinting")
> Fixes: d70159cb62f5 ("dts: add params manipulation module")
> Fixes: 967fc62b0a43 ("dts: refactor EAL parameters class")
> Fixes: 818fe14e3422 ("dts: add parsing utility module")
> Cc: luca.vizzarro@arm.com
>
> Signed-off-by: Juraj Linkeš <juraj.linkes@pantheon.tech>
> Reviewed-by: Luca Vizzarro <luca.vizzarro@arm.com>
> ---
Reviewed-by: Jeremy Spewock <jspewock@iol.unh.edu>
@@ -53,9 +53,9 @@ def reduced_fn(value):
def modify_str(*funcs: FnPtr) -> Callable[[T], T]:
- """Class decorator modifying the ``__str__`` method with a function created from its arguments.
+ r"""Class decorator modifying the ``__str__`` method with a function created from its arguments.
- The :attr:`FnPtr`s fed to the decorator are executed from left to right in the arguments list
+ The :attr:`FnPtr`\s fed to the decorator are executed from left to right in the arguments list
order.
Args:
@@ -26,13 +26,16 @@ class EalParams(Params):
prefix: Set the file prefix string with which to start DPDK, e.g.: ``prefix="vf"``.
no_pci: Switch to disable PCI bus, e.g.: ``no_pci=True``.
vdevs: Virtual devices, e.g.::
+
vdevs=[
VirtualDevice('net_ring0'),
VirtualDevice('net_ring1')
]
+
ports: The list of ports to allow.
- other_eal_param: user defined DPDK EAL parameters, e.g.:
- ``other_eal_param='--single-file-segments'``
+ other_eal_param: user defined DPDK EAL parameters, e.g.::
+
+ ``other_eal_param='--single-file-segments'``
"""
lcore_list: LogicalCoreList | None = field(default=None, metadata=Params.short("l"))
@@ -6,7 +6,8 @@
TypedDicts can be used in conjunction with Unpack and kwargs for type hinting on function calls.
Example:
- ..code:: python
+ .. code:: python
+
def create_testpmd(**kwargs: Unpack[TestPmdParamsDict]):
params = TestPmdParams(**kwargs)
"""
@@ -46,7 +46,7 @@ class TextParser(ABC):
Example:
The following example makes use of and demonstrates every parser function available:
- ..code:: python
+ .. code:: python
from dataclasses import dataclass, field
from enum import Enum
@@ -90,7 +90,7 @@ def wrap(parser_fn: ParserFn, wrapper_fn: Callable) -> ParserFn:
"""Makes a wrapped parser function.
`parser_fn` is called and if a non-None value is returned, `wrapper_function` is called with
- it. Otherwise the function returns early with None. In pseudo-code:
+ it. Otherwise the function returns early with None. In pseudo-code::
intermediate_value := parser_fn(input)
if intermediary_value is None then