diff mbox series

[v4,2/3] dts: add API doc sources

Message ID 20240412101405.94377-3-juraj.linkes@pantheon.tech (mailing list archive)
State Superseded, archived
Delegated to: Thomas Monjalon
Headers
Series dts: API docs generation |

Checks

Context Check Description
ci/checkpatch success coding style OK

Commit Message

Juraj Linkeš April 12, 2024, 10:14 a.m. UTC 
These sources could be generated with the sphinx-apidoc utility, but
that doesn't give us enough flexibility, such as sorting the order of
modules or changing the headers of the modules.

The sources included in this patch were in fact generated by said
utility, but modified to improve the look of the documentation. The
improvements are mainly in toctree definitions and the titles of the
modules/packages. These were made with specific Sphinx config options in
mind.

Signed-off-by: Juraj Linkeš <juraj.linkes@pantheon.tech>
---
 dts/doc/conf_yaml_schema.json                 |  1 +
 dts/doc/framework.config.rst                  | 12 ++++++
 dts/doc/framework.config.types.rst            |  6 +++
 dts/doc/framework.exception.rst               |  6 +++
 dts/doc/framework.logger.rst                  |  6 +++
 ...ote_session.interactive_remote_session.rst |  6 +++
 ...ework.remote_session.interactive_shell.rst |  6 +++
 .../framework.remote_session.python_shell.rst |  6 +++
 ...ramework.remote_session.remote_session.rst |  6 +++
 dts/doc/framework.remote_session.rst          | 17 ++++++++
 .../framework.remote_session.ssh_session.rst  |  6 +++
 ...framework.remote_session.testpmd_shell.rst |  6 +++
 dts/doc/framework.runner.rst                  |  6 +++
 dts/doc/framework.settings.rst                |  6 +++
 dts/doc/framework.test_result.rst             |  6 +++
 dts/doc/framework.test_suite.rst              |  6 +++
 dts/doc/framework.testbed_model.cpu.rst       |  6 +++
 .../framework.testbed_model.linux_session.rst |  6 +++
 dts/doc/framework.testbed_model.node.rst      |  6 +++
 .../framework.testbed_model.os_session.rst    |  6 +++
 dts/doc/framework.testbed_model.port.rst      |  6 +++
 .../framework.testbed_model.posix_session.rst |  6 +++
 dts/doc/framework.testbed_model.rst           | 26 ++++++++++++
 dts/doc/framework.testbed_model.sut_node.rst  |  6 +++
 dts/doc/framework.testbed_model.tg_node.rst   |  6 +++
 ..._generator.capturing_traffic_generator.rst |  6 +++
 ...mework.testbed_model.traffic_generator.rst | 14 +++++++
 ....testbed_model.traffic_generator.scapy.rst |  6 +++
 ...el.traffic_generator.traffic_generator.rst |  6 +++
 ...framework.testbed_model.virtual_device.rst |  6 +++
 dts/doc/framework.utils.rst                   |  6 +++
 dts/doc/index.rst                             | 41 +++++++++++++++++++
 32 files changed, 267 insertions(+)
 create mode 120000 dts/doc/conf_yaml_schema.json
 create mode 100644 dts/doc/framework.config.rst
 create mode 100644 dts/doc/framework.config.types.rst
 create mode 100644 dts/doc/framework.exception.rst
 create mode 100644 dts/doc/framework.logger.rst
 create mode 100644 dts/doc/framework.remote_session.interactive_remote_session.rst
 create mode 100644 dts/doc/framework.remote_session.interactive_shell.rst
 create mode 100644 dts/doc/framework.remote_session.python_shell.rst
 create mode 100644 dts/doc/framework.remote_session.remote_session.rst
 create mode 100644 dts/doc/framework.remote_session.rst
 create mode 100644 dts/doc/framework.remote_session.ssh_session.rst
 create mode 100644 dts/doc/framework.remote_session.testpmd_shell.rst
 create mode 100644 dts/doc/framework.runner.rst
 create mode 100644 dts/doc/framework.settings.rst
 create mode 100644 dts/doc/framework.test_result.rst
 create mode 100644 dts/doc/framework.test_suite.rst
 create mode 100644 dts/doc/framework.testbed_model.cpu.rst
 create mode 100644 dts/doc/framework.testbed_model.linux_session.rst
 create mode 100644 dts/doc/framework.testbed_model.node.rst
 create mode 100644 dts/doc/framework.testbed_model.os_session.rst
 create mode 100644 dts/doc/framework.testbed_model.port.rst
 create mode 100644 dts/doc/framework.testbed_model.posix_session.rst
 create mode 100644 dts/doc/framework.testbed_model.rst
 create mode 100644 dts/doc/framework.testbed_model.sut_node.rst
 create mode 100644 dts/doc/framework.testbed_model.tg_node.rst
 create mode 100644 dts/doc/framework.testbed_model.traffic_generator.capturing_traffic_generator.rst
 create mode 100644 dts/doc/framework.testbed_model.traffic_generator.rst
 create mode 100644 dts/doc/framework.testbed_model.traffic_generator.scapy.rst
 create mode 100644 dts/doc/framework.testbed_model.traffic_generator.traffic_generator.rst
 create mode 100644 dts/doc/framework.testbed_model.virtual_device.rst
 create mode 100644 dts/doc/framework.utils.rst
 create mode 100644 dts/doc/index.rst

Comments

Luca Vizzarro May 31, 2024, 10:43 a.m. UTC | #1 
Reviewed-by: Luca Vizzarro <luca.vizzarro@arm.com>
Tested-by: Luca Vizzarro <luca.vizzarro@arm.com>
Jeremy Spewock June 14, 2024, 2:32 p.m. UTC | #2 
I noticed one small typo but otherwise:

Reviewed-by: Jeremy Spewock <jspewock@iol.unh.edu>

On Fri, Apr 12, 2024 at 6:14 AM Juraj Linkeš <juraj.linkes@pantheon.tech> wrote:
>
> These sources could be generated with the sphinx-apidoc utility, but
> that doesn't give us enough flexibility, such as sorting the order of
> modules or changing the headers of the modules.
>
> The sources included in this patch were in fact generated by said
> utility, but modified to improve the look of the documentation. The
> improvements are mainly in toctree definitions and the titles of the
> modules/packages. These were made with specific Sphinx config options in
> mind.
>
> Signed-off-by: Juraj Linkeš <juraj.linkes@pantheon.tech>
> ---
<snip>
> diff --git a/dts/doc/framework.testbed_model.tg_node.rst b/dts/doc/framework.testbed_model.tg_node.rst
> new file mode 100644
> index 0000000000..41206c000b
> --- /dev/null
> +++ b/dts/doc/framework.testbed_model.tg_node.rst
> @@ -0,0 +1,6 @@
> +tg\_node - Traffig Generator Node

Typo: Traffic Generator Node

> +=================================
<snip>
> 2.34.1
>
diff mbox series

Patch

diff --git a/dts/doc/conf_yaml_schema.json b/dts/doc/conf_yaml_schema.json
new file mode 120000
index 0000000000..d89eb81b72
--- /dev/null
+++ b/dts/doc/conf_yaml_schema.json
@@ -0,0 +1 @@ 
+../framework/config/conf_yaml_schema.json
\ No newline at end of file
diff --git a/dts/doc/framework.config.rst b/dts/doc/framework.config.rst
new file mode 100644
index 0000000000..f765ef0e32
--- /dev/null
+++ b/dts/doc/framework.config.rst
@@ -0,0 +1,12 @@ 
+config - Configuration Package
+==============================
+
+.. automodule:: framework.config
+   :members:
+   :show-inheritance:
+
+.. toctree::
+   :hidden:
+   :maxdepth: 1
+
+   framework.config.types
diff --git a/dts/doc/framework.config.types.rst b/dts/doc/framework.config.types.rst
new file mode 100644
index 0000000000..5af915b681
--- /dev/null
+++ b/dts/doc/framework.config.types.rst
@@ -0,0 +1,6 @@ 
+types - Configuration Types
+===========================
+
+.. automodule:: framework.config.types
+   :members:
+   :show-inheritance:
diff --git a/dts/doc/framework.exception.rst b/dts/doc/framework.exception.rst
new file mode 100644
index 0000000000..ad58bd15de
--- /dev/null
+++ b/dts/doc/framework.exception.rst
@@ -0,0 +1,6 @@ 
+exception - Exceptions
+======================
+
+.. automodule:: framework.exception
+   :members:
+   :show-inheritance:
diff --git a/dts/doc/framework.logger.rst b/dts/doc/framework.logger.rst
new file mode 100644
index 0000000000..3c25b34819
--- /dev/null
+++ b/dts/doc/framework.logger.rst
@@ -0,0 +1,6 @@ 
+logger - Logging Facility
+=========================
+
+.. automodule:: framework.logger
+   :members:
+   :show-inheritance:
diff --git a/dts/doc/framework.remote_session.interactive_remote_session.rst b/dts/doc/framework.remote_session.interactive_remote_session.rst
new file mode 100644
index 0000000000..35dc5c4b03
--- /dev/null
+++ b/dts/doc/framework.remote_session.interactive_remote_session.rst
@@ -0,0 +1,6 @@ 
+interactive\_remote\_session - SSH Interactive Remote Session
+=============================================================
+
+.. automodule:: framework.remote_session.interactive_remote_session
+   :members:
+   :show-inheritance:
diff --git a/dts/doc/framework.remote_session.interactive_shell.rst b/dts/doc/framework.remote_session.interactive_shell.rst
new file mode 100644
index 0000000000..8a59db7b6e
--- /dev/null
+++ b/dts/doc/framework.remote_session.interactive_shell.rst
@@ -0,0 +1,6 @@ 
+interactive\_shell - Base Interactive Remote Shell
+==================================================
+
+.. automodule:: framework.remote_session.interactive_shell
+   :members:
+   :show-inheritance:
diff --git a/dts/doc/framework.remote_session.python_shell.rst b/dts/doc/framework.remote_session.python_shell.rst
new file mode 100644
index 0000000000..a8ec06f281
--- /dev/null
+++ b/dts/doc/framework.remote_session.python_shell.rst
@@ -0,0 +1,6 @@ 
+python\_shell - Python Interactive Remote Shell
+===============================================
+
+.. automodule:: framework.remote_session.python_shell
+   :members:
+   :show-inheritance:
diff --git a/dts/doc/framework.remote_session.remote_session.rst b/dts/doc/framework.remote_session.remote_session.rst
new file mode 100644
index 0000000000..58b0960d07
--- /dev/null
+++ b/dts/doc/framework.remote_session.remote_session.rst
@@ -0,0 +1,6 @@ 
+remote\_session - Remote Session ABC
+====================================
+
+.. automodule:: framework.remote_session.remote_session
+   :members:
+   :show-inheritance:
diff --git a/dts/doc/framework.remote_session.rst b/dts/doc/framework.remote_session.rst
new file mode 100644
index 0000000000..74f83f0307
--- /dev/null
+++ b/dts/doc/framework.remote_session.rst
@@ -0,0 +1,17 @@ 
+remote\_session - Node Connections Package
+==========================================
+
+.. automodule:: framework.remote_session
+   :members:
+   :show-inheritance:
+
+.. toctree::
+   :hidden:
+   :maxdepth: 1
+
+   framework.remote_session.remote_session
+   framework.remote_session.ssh_session
+   framework.remote_session.interactive_remote_session
+   framework.remote_session.interactive_shell
+   framework.remote_session.testpmd_shell
+   framework.remote_session.python_shell
diff --git a/dts/doc/framework.remote_session.ssh_session.rst b/dts/doc/framework.remote_session.ssh_session.rst
new file mode 100644
index 0000000000..05b019bc7c
--- /dev/null
+++ b/dts/doc/framework.remote_session.ssh_session.rst
@@ -0,0 +1,6 @@ 
+ssh\_session - SSH Remote Session
+=================================
+
+.. automodule:: framework.remote_session.ssh_session
+   :members:
+   :show-inheritance:
diff --git a/dts/doc/framework.remote_session.testpmd_shell.rst b/dts/doc/framework.remote_session.testpmd_shell.rst
new file mode 100644
index 0000000000..14510afb2b
--- /dev/null
+++ b/dts/doc/framework.remote_session.testpmd_shell.rst
@@ -0,0 +1,6 @@ 
+testpmd\_shell - Testpmd Interactive Remote Shell
+=================================================
+
+.. automodule:: framework.remote_session.testpmd_shell
+   :members:
+   :show-inheritance:
diff --git a/dts/doc/framework.runner.rst b/dts/doc/framework.runner.rst
new file mode 100644
index 0000000000..a1708f0002
--- /dev/null
+++ b/dts/doc/framework.runner.rst
@@ -0,0 +1,6 @@ 
+runner - Testbed Setup and Test Suite Runner
+============================================
+
+.. automodule:: framework.runner
+   :members:
+   :show-inheritance:
diff --git a/dts/doc/framework.settings.rst b/dts/doc/framework.settings.rst
new file mode 100644
index 0000000000..96bf194923
--- /dev/null
+++ b/dts/doc/framework.settings.rst
@@ -0,0 +1,6 @@ 
+settings - Command Line Arguments and Environment Variables
+===========================================================
+
+.. automodule:: framework.settings
+   :members:
+   :show-inheritance:
diff --git a/dts/doc/framework.test_result.rst b/dts/doc/framework.test_result.rst
new file mode 100644
index 0000000000..527357a04a
--- /dev/null
+++ b/dts/doc/framework.test_result.rst
@@ -0,0 +1,6 @@ 
+test\_result - Test Results Records
+===================================
+
+.. automodule:: framework.test_result
+   :members:
+   :show-inheritance:
diff --git a/dts/doc/framework.test_suite.rst b/dts/doc/framework.test_suite.rst
new file mode 100644
index 0000000000..96f893e465
--- /dev/null
+++ b/dts/doc/framework.test_suite.rst
@@ -0,0 +1,6 @@ 
+test\_suite - Common Test Suite Features
+========================================
+
+.. automodule:: framework.test_suite
+   :members:
+   :show-inheritance:
diff --git a/dts/doc/framework.testbed_model.cpu.rst b/dts/doc/framework.testbed_model.cpu.rst
new file mode 100644
index 0000000000..dd2baf09fb
--- /dev/null
+++ b/dts/doc/framework.testbed_model.cpu.rst
@@ -0,0 +1,6 @@ 
+cpu - CPU Representation and Utilities
+======================================
+
+.. automodule:: framework.testbed_model.cpu
+   :members:
+   :show-inheritance:
diff --git a/dts/doc/framework.testbed_model.linux_session.rst b/dts/doc/framework.testbed_model.linux_session.rst
new file mode 100644
index 0000000000..141f3f49e3
--- /dev/null
+++ b/dts/doc/framework.testbed_model.linux_session.rst
@@ -0,0 +1,6 @@ 
+linux\_session - Linux Remote Session
+=====================================
+
+.. automodule:: framework.testbed_model.linux_session
+   :members:
+   :show-inheritance:
diff --git a/dts/doc/framework.testbed_model.node.rst b/dts/doc/framework.testbed_model.node.rst
new file mode 100644
index 0000000000..2133dd604b
--- /dev/null
+++ b/dts/doc/framework.testbed_model.node.rst
@@ -0,0 +1,6 @@ 
+node - Base Node
+================
+
+.. automodule:: framework.testbed_model.node
+   :members:
+   :show-inheritance:
diff --git a/dts/doc/framework.testbed_model.os_session.rst b/dts/doc/framework.testbed_model.os_session.rst
new file mode 100644
index 0000000000..f3574e939a
--- /dev/null
+++ b/dts/doc/framework.testbed_model.os_session.rst
@@ -0,0 +1,6 @@ 
+os\_session - OS-aware Remote Session ABC
+=========================================
+
+.. automodule:: framework.testbed_model.os_session
+   :members:
+   :show-inheritance:
diff --git a/dts/doc/framework.testbed_model.port.rst b/dts/doc/framework.testbed_model.port.rst
new file mode 100644
index 0000000000..17bd391e63
--- /dev/null
+++ b/dts/doc/framework.testbed_model.port.rst
@@ -0,0 +1,6 @@ 
+port - NIC Port Representation
+==============================
+
+.. automodule:: framework.testbed_model.port
+   :members:
+   :show-inheritance:
diff --git a/dts/doc/framework.testbed_model.posix_session.rst b/dts/doc/framework.testbed_model.posix_session.rst
new file mode 100644
index 0000000000..308c051ae5
--- /dev/null
+++ b/dts/doc/framework.testbed_model.posix_session.rst
@@ -0,0 +1,6 @@ 
+posix\_session - Posix Remote Session
+=====================================
+
+.. automodule:: framework.testbed_model.posix_session
+   :members:
+   :show-inheritance:
diff --git a/dts/doc/framework.testbed_model.rst b/dts/doc/framework.testbed_model.rst
new file mode 100644
index 0000000000..4b024e47e6
--- /dev/null
+++ b/dts/doc/framework.testbed_model.rst
@@ -0,0 +1,26 @@ 
+testbed\_model - Testbed Modelling Package
+==========================================
+
+.. automodule:: framework.testbed_model
+   :members:
+   :show-inheritance:
+
+.. toctree::
+   :hidden:
+   :maxdepth: 2
+
+   framework.testbed_model.traffic_generator
+
+.. toctree::
+   :hidden:
+   :maxdepth: 1
+
+   framework.testbed_model.os_session
+   framework.testbed_model.linux_session
+   framework.testbed_model.posix_session
+   framework.testbed_model.node
+   framework.testbed_model.sut_node
+   framework.testbed_model.tg_node
+   framework.testbed_model.cpu
+   framework.testbed_model.port
+   framework.testbed_model.virtual_device
diff --git a/dts/doc/framework.testbed_model.sut_node.rst b/dts/doc/framework.testbed_model.sut_node.rst
new file mode 100644
index 0000000000..7e12b6c87e
--- /dev/null
+++ b/dts/doc/framework.testbed_model.sut_node.rst
@@ -0,0 +1,6 @@ 
+sut\_node - System Under Test Node
+==================================
+
+.. automodule:: framework.testbed_model.sut_node
+   :members:
+   :show-inheritance:
diff --git a/dts/doc/framework.testbed_model.tg_node.rst b/dts/doc/framework.testbed_model.tg_node.rst
new file mode 100644
index 0000000000..41206c000b
--- /dev/null
+++ b/dts/doc/framework.testbed_model.tg_node.rst
@@ -0,0 +1,6 @@ 
+tg\_node - Traffig Generator Node
+=================================
+
+.. automodule:: framework.testbed_model.tg_node
+   :members:
+   :show-inheritance:
diff --git a/dts/doc/framework.testbed_model.traffic_generator.capturing_traffic_generator.rst b/dts/doc/framework.testbed_model.traffic_generator.capturing_traffic_generator.rst
new file mode 100644
index 0000000000..06c087155a
--- /dev/null
+++ b/dts/doc/framework.testbed_model.traffic_generator.capturing_traffic_generator.rst
@@ -0,0 +1,6 @@ 
+capturing\_traffic\_generator - Base Capturing TG ABC
+=====================================================
+
+.. automodule:: framework.testbed_model.traffic_generator.capturing_traffic_generator
+   :members:
+   :show-inheritance:
diff --git a/dts/doc/framework.testbed_model.traffic_generator.rst b/dts/doc/framework.testbed_model.traffic_generator.rst
new file mode 100644
index 0000000000..18b6f1b98b
--- /dev/null
+++ b/dts/doc/framework.testbed_model.traffic_generator.rst
@@ -0,0 +1,14 @@ 
+traffic\_generator Subpackage
+=============================
+
+.. automodule:: framework.testbed_model.traffic_generator
+   :members:
+   :show-inheritance:
+
+.. toctree::
+   :hidden:
+   :maxdepth: 1
+
+   framework.testbed_model.traffic_generator.traffic_generator
+   framework.testbed_model.traffic_generator.capturing_traffic_generator
+   framework.testbed_model.traffic_generator.scapy
diff --git a/dts/doc/framework.testbed_model.traffic_generator.scapy.rst b/dts/doc/framework.testbed_model.traffic_generator.scapy.rst
new file mode 100644
index 0000000000..7062914ec3
--- /dev/null
+++ b/dts/doc/framework.testbed_model.traffic_generator.scapy.rst
@@ -0,0 +1,6 @@ 
+scapy - Capturing Traffic Generator
+===================================
+
+.. automodule:: framework.testbed_model.traffic_generator.scapy
+   :members:
+   :show-inheritance:
diff --git a/dts/doc/framework.testbed_model.traffic_generator.traffic_generator.rst b/dts/doc/framework.testbed_model.traffic_generator.traffic_generator.rst
new file mode 100644
index 0000000000..e366d7f222
--- /dev/null
+++ b/dts/doc/framework.testbed_model.traffic_generator.traffic_generator.rst
@@ -0,0 +1,6 @@ 
+traffic\_generator - Base TG ABC
+================================
+
+.. automodule:: framework.testbed_model.traffic_generator.traffic_generator
+   :members:
+   :show-inheritance:
diff --git a/dts/doc/framework.testbed_model.virtual_device.rst b/dts/doc/framework.testbed_model.virtual_device.rst
new file mode 100644
index 0000000000..38e6c1d0bc
--- /dev/null
+++ b/dts/doc/framework.testbed_model.virtual_device.rst
@@ -0,0 +1,6 @@ 
+virtual\_device - Virtual Devices
+=================================
+
+.. automodule:: framework.testbed_model.virtual_device
+   :members:
+   :show-inheritance:
diff --git a/dts/doc/framework.utils.rst b/dts/doc/framework.utils.rst
new file mode 100644
index 0000000000..0e7bb80666
--- /dev/null
+++ b/dts/doc/framework.utils.rst
@@ -0,0 +1,6 @@ 
+utils - Various Utilities
+=========================
+
+.. automodule:: framework.utils
+   :members:
+   :show-inheritance:
diff --git a/dts/doc/index.rst b/dts/doc/index.rst
new file mode 100644
index 0000000000..501e7204a7
--- /dev/null
+++ b/dts/doc/index.rst
@@ -0,0 +1,41 @@ 
+.. DPDK Test Suite documentation.
+
+Welcome to DPDK Test Suite's API documentation!
+===============================================
+
+.. automodule:: framework
+   :members:
+   :show-inheritance:
+
+Packages
+--------
+
+.. toctree::
+   :includehidden:
+   :maxdepth: 1
+
+   framework.testbed_model
+   framework.remote_session
+   framework.config
+
+Modules
+-------
+
+.. toctree::
+   :maxdepth: 1
+
+   framework.runner
+   framework.test_suite
+   framework.test_result
+   framework.settings
+   framework.logger
+   framework.utils
+   framework.exception
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`