From 958ff41826921275d09ee9bfc6a8ba70878af2fa Mon Sep 17 00:00:00 2001 From: Andrew Vaillancourt Date: Mon, 3 Feb 2025 14:56:26 -0500 Subject: [PATCH] Add basic documentation skeleton Introduced a basic documentation skeleton that mirrors the flat directory structure of starlingx/test, providing a foundation for future documentation expansion. Structured documentation layout based on starlingx/test directories: - Created placeholder index.rst files for: - config/ - framework/ - keywords/ - resources/ - scripts/ - testcases/ - unit_tests/ - web_pages/ - Ensured modular navigation through toctree references Repository overview & navigation improvements: - Added directory_structure.rst to document the current repository layout - Updated index.rst to provide a central entry point for navigating documentation - Ensured logical linking between sections for future expansion Initial content in resources/: - Unlike other sections, resources/ contains actual documentation beyond a placeholder - Added resources_overview.rst, covering containerized applications, test images, and nightly regression configs Verified with Sphinx live preview (sphinx-autobuild). No API documentation yet, just a basic high-level skeleton for the repository's directories. Change-Id: I5f21199280c4c472cd812021bf0f9c3fa6f5c967 Signed-off-by: Andrew Vaillancourt --- doc/source/config/index.rst | 11 ++ doc/source/directory_structure.rst | 40 ++++++++ doc/source/framework/index.rst | 11 ++ doc/source/index.rst | 35 ++++--- doc/source/keywords/index.rst | 11 ++ doc/source/resources/index.rst | 45 ++++++++ doc/source/resources/resources_overview.rst | 107 ++++++++++++++++++++ doc/source/scripts/index.rst | 11 ++ doc/source/testcases/index.rst | 17 ++-- doc/source/unit_tests/index.rst | 11 ++ doc/source/web_pages/index.rst | 11 ++ 11 files changed, 287 insertions(+), 23 deletions(-) create mode 100644 doc/source/config/index.rst create mode 100644 doc/source/directory_structure.rst create mode 100644 doc/source/framework/index.rst create mode 100644 doc/source/keywords/index.rst create mode 100644 doc/source/resources/index.rst create mode 100644 doc/source/resources/resources_overview.rst create mode 100644 doc/source/scripts/index.rst create mode 100644 doc/source/unit_tests/index.rst create mode 100644 doc/source/web_pages/index.rst diff --git a/doc/source/config/index.rst b/doc/source/config/index.rst new file mode 100644 index 00000000..9cdc765d --- /dev/null +++ b/doc/source/config/index.rst @@ -0,0 +1,11 @@ +========================= +**config/** Documentation +========================= + +This section covers **configuration-related components** in the StarlingX test framework. + +-------- +Contents +-------- + +*(Additional configuration documentation will be added here.)* diff --git a/doc/source/directory_structure.rst b/doc/source/directory_structure.rst new file mode 100644 index 00000000..e8b02e97 --- /dev/null +++ b/doc/source/directory_structure.rst @@ -0,0 +1,40 @@ +=================================== +StarlingX Test Repository Structure +=================================== + +Below is an overview of the `starlingx/test` directory structure. +This highlights key directories but does not list every file. + +.. code-block:: bash + + starlingx/test/ + ├── config + ├── doc + ├── framework + ├── keywords + ├── portal + ├── pre-commit + ├── releasenotes + ├── resources + ├── scripts + ├── testcases + ├── unit_tests + └── web_pages + +----------- +Directories +----------- + +For detailed information on specific directories, see the pages below. + +.. toctree:: + :maxdepth: 1 + + testcases/index + resources/index + framework/index + keywords/index + config/index + scripts/index + unit_tests/index + web_pages/index diff --git a/doc/source/framework/index.rst b/doc/source/framework/index.rst new file mode 100644 index 00000000..e9334d20 --- /dev/null +++ b/doc/source/framework/index.rst @@ -0,0 +1,11 @@ +============================ +**framework/** Documentation +============================ + +This section covers the **testing framework** used in StarlingX. + +-------- +Contents +-------- + +*(Additional framework documentation will be added here.)* diff --git a/doc/source/index.rst b/doc/source/index.rst index ba68a70f..9f6cb39e 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -1,27 +1,32 @@ -====================== -stx-test Documentation -====================== +============================== +StarlingX Test Documentation +============================== -This is the documentation for StarlingX Test. +------------ +Introduction +------------ +This project contains **Automated Test Cases** that validate the **StarlingX product**. +The test framework provides tools and structured test cases to ensure the stability and reliability of StarlingX components. --------- -Sections --------- +For more information about StarlingX, see the official documentation: +🔗 https://docs.starlingx.io/ + +---------------------- +Repository Structure +---------------------- + +The **StarlingX Test Repository Structure** provides an overview of key directories and their purpose within the automation framework. .. toctree:: :maxdepth: 1 - testcases/index + directory_structure ----- Links ----- -* Source: `stx-test`_ -* Code Review: `Gerrit`_ -* Bugs: `Storyboard`_ - -.. _stx-test: https://opendev.org/starlingx/test -.. _Gerrit: https://review.opendev.org/#/q/project:starlingx/test -.. _Storyboard: https://storyboard.openstack.org/#!/project/starlingx/test \ No newline at end of file +* **Source Code:** https://opendev.org/starlingx/test +* **Code Review:** https://review.opendev.org/#/q/project:starlingx/test +* **Bug Tracking:** https://storyboard.openstack.org/#!/project/starlingx/test diff --git a/doc/source/keywords/index.rst b/doc/source/keywords/index.rst new file mode 100644 index 00000000..9794826d --- /dev/null +++ b/doc/source/keywords/index.rst @@ -0,0 +1,11 @@ +=========================== +**keywords/** Documentation +=========================== + +This section covers **keyword-based automation** within the StarlingX test framework. + +-------- +Contents +-------- + +*(Additional keyword documentation will be added here.)* diff --git a/doc/source/resources/index.rst b/doc/source/resources/index.rst new file mode 100644 index 00000000..68017d21 --- /dev/null +++ b/doc/source/resources/index.rst @@ -0,0 +1,45 @@ +============================ +**resources/** Documentation +============================ + +The **resources/** directory contains various test-related assets used within the StarlingX Test Framework, +including containerized applications, custom-built Docker images, nightly regression configurations +(deployment files, pod definitions, and Network Attachment Definitions (NADs)), and sanity test pods / configs. + +-------- +Contents +-------- + +.. toctree:: + :maxdepth: 1 + + resources_overview + +Directory Structure +======================= + +Below is an overview of the **resources/** directory structure. +This highlights key directories and files but does not include every file: + +.. code-block:: bash + + resources/ + ├── cloud_platform + │ ├── containers + │ │ ├── hello-kitty_armada.tgz + │ │ ├── hello-kitty-min-k8s-version.tgz + │ ├── images + │ │ └── node-hello-alpine + │ │ ├── Dockerfile + │ │ ├── node-hello-alpine.tar.gz + │ │ └── server.js + │ ├── nightly_regression + │ │ ├── calicoctl_crb.yaml + │ │ └── daemon_set_daemonset_ipv4.yaml + │ ├── sanity + │ └── pods + │ ├── client-pod1.yaml + │ └── server_pod.yaml + ├── images + ├── busybox.tar + └── calico-ctl.tar diff --git a/doc/source/resources/resources_overview.rst b/doc/source/resources/resources_overview.rst new file mode 100644 index 00000000..b9ee4fc6 --- /dev/null +++ b/doc/source/resources/resources_overview.rst @@ -0,0 +1,107 @@ +.. _resources-overview: + +======================= +Resources Overview +======================= + +The **resources/** directory contains various test-related assets used within the StarlingX Test Framework, +including containerized applications, custom-built Docker images, nightly regression configurations +(deployment files, pod definitions, and Network Attachment Definitions (NADs)), and sanity test pods / configs. + +Directory Structure +======================= + +Below is an overview of the **resources/** directory structure. +This highlights key directories and files but does not include every file: + +.. code-block:: bash + + resources/ + ├── cloud_platform + │ ├── containers + │ │ ├── hello-kitty_armada.tgz + │ │ ├── hello-kitty-min-k8s-version.tgz + │ ├── images + │ │ └── node-hello-alpine + │ │ ├── Dockerfile + │ │ ├── node-hello-alpine.tar.gz + │ │ └── server.js + │ ├── nightly_regression + │ │ ├── calicoctl_crb.yaml + │ │ └── daemon_set_daemonset_ipv4.yaml + │ ├── sanity + │ └── pods + │ ├── client-pod1.yaml + │ └── server_pod.yaml + ├── images + ├── busybox.tar + └── calico-ctl.tar + +resources/cloud_platform/containers +----------------------------------- + +Contains **packaged containerized applications** in Helm and FluxCD formats for Kubernetes-based testing. + +**Example files:** + +- ``hello-kitty.tgz`` (FluxCD deployment package with Helm charts) +- ``hello-kitty_armada.tgz`` (Armada manifest for Helm-based Kubernetes deployments) +- ``hello-kitty-min-k8s-version.tgz`` (Minimal Helm chart version with Kubernetes version constraints, including FluxCD manifests) +- ``hello-kitty_no_secret.tgz`` (Variant of `hello-kitty` with no secrets in the deployment) + +resources/cloud_platform/images +-------------------------------- + +Contains **custom-built container images** for cloud platform validation. + +- ``node-hello-alpine/`` (Directory containing the Docker build context for a Node.js application) + + - ``node-hello-alpine.tar.gz`` (Pre-built Docker image for the Node.js application) + - ``Dockerfile`` (Defines how to build the `node-hello-alpine` Docker image) + - ``server.js`` (Node.js application file that runs inside the container) + +resources/cloud_platform/nightly_regression +------------------------------------------- + +Contains **YAML configuration files** used for nightly regression testing. + +**Example files:** + +- ``calicoctl_crb.yaml`` (Calico ClusterRoleBinding configuration) +- ``calicoctl_cr.yaml`` (Calico ClusterRole configuration) +- ``daemon_set_daemonset_ipv4.yaml`` (DaemonSet definition for IPv4 testing) +- ``netdef_test-sriovdp_ipv4_with_pools.yaml`` (Network definition for SR-IOV device plugin with IPv4 pools) + +resources/cloud_platform/sanity/pods +------------------------------------- + +Contains **sanity test pod definitions** used for basic Kubernetes validation. + +**Example files:** + +- ``client-pod1.yaml`` (Kubernetes client pod configuration) +- ``consumer_app.yaml`` (Pod definition for a consumer application in sanity testing) +- ``server_pod.yaml`` (Server pod used for network testing) + +resources/images +----------------- + +Contains **general-purpose Docker images** used across multiple test cases. + +**Example files:** + +- ``busybox.tar`` (Docker image) +- ``pv-test.tar`` (Docker image) +- ``calico-ctl.tar`` (Docker image) +- ``resource-consumer.tar`` (Docker image) + +Key Takeaways +======================= + +- ``resources/cloud_platform/containers`` → **Packaged Kubernetes applications** (Helm charts, FluxCD deployments) +- ``resources/cloud_platform/images`` → **Custom-built Docker images** for cloud platform testing +- ``resources/cloud_platform/nightly_regression`` → **Nightly regression test configurations** (Calico, DaemonSets, Network definitions, etc.) +- ``resources/cloud_platform/sanity/pods`` → **Sanity test pod configurations** for Kubernetes validation +- ``resources/images`` → **General-purpose container images** for various automation tests + +This structure ensures clarity, modularity, and efficient resource management within the StarlingX test framework. diff --git a/doc/source/scripts/index.rst b/doc/source/scripts/index.rst new file mode 100644 index 00000000..8bf09e83 --- /dev/null +++ b/doc/source/scripts/index.rst @@ -0,0 +1,11 @@ +========================== +**scripts/** Documentation +========================== + +This section covers various **helper scripts** used for test execution and automation. + +-------- +Contents +-------- + +*(Additional script documentation will be added here.)* diff --git a/doc/source/testcases/index.rst b/doc/source/testcases/index.rst index a7680638..4f7c10e6 100644 --- a/doc/source/testcases/index.rst +++ b/doc/source/testcases/index.rst @@ -1,10 +1,11 @@ -=============================== -StarlingX Automation Framework -=============================== +============================ +**testcases/** Documentation +============================ ------------- -Introduction ------------- +This section contains documentation related to **automated test cases** used in the StarlingX test framework. -This project contains Automated Test Cases that validate the StarlingX product. -For more information about StarlingX, see https://docs.starlingx.io/. \ No newline at end of file +-------- +Contents +-------- + +*(Detailed documentation on test case structure, execution, and examples will be added here.)* diff --git a/doc/source/unit_tests/index.rst b/doc/source/unit_tests/index.rst new file mode 100644 index 00000000..0343dff7 --- /dev/null +++ b/doc/source/unit_tests/index.rst @@ -0,0 +1,11 @@ +============================= +**unit_tests/** Documentation +============================= + +This section covers **unit testing** within the StarlingX test framework. + +-------- +Contents +-------- + +*(Additional unit test documentation will be added here.)* diff --git a/doc/source/web_pages/index.rst b/doc/source/web_pages/index.rst new file mode 100644 index 00000000..dff9d5a1 --- /dev/null +++ b/doc/source/web_pages/index.rst @@ -0,0 +1,11 @@ +============================ +**web_pages/** Documentation +============================ + +This section covers **web-based testing** and automation components. + +-------- +Contents +-------- + +*(Additional web page automation documentation will be added here.)*