starlingx/test
Code Issues Proposed changes
test/doc/source/index.rst
Andrew Vaillancourt 1b9396a2c6 Enforce docstring standards and update pre-commit 
- Enforce Google-style docstrings in pre-commit hooks:
  - Add pydocstyle, pydoclint, and interrogate to Pipenv and pre-commit
  - Configure pydocstyle for PEP 257 and Google-style compliance
  - Set pydoclint to enforce function signature correctness
  - Ensure 100% function and class docstring coverage with interrogate:
    - There are some exceptions, e.g. init, module-level.
    - More exceptions can be added if the tooling is found to be too
      strict.

- Refine Black hook ordering to ensure all hooks run on formatted files:
  - Fail commit if formatting is needed (--check)
  - Auto-format files in a separate step
  - Prevent bypassing docstring checks by staging unformatted files

- Ensure return type consistency (DOC203 best practices):
  - Require both return type hints (-> type) and docstring return types
  - Explain rationale for requiring both:
    - Type hints help with static analysis and runtime type checking
    - Docstring return types improve readability and documentation clarity
    - Pre-commit hooks validate consistency across both formats
  - Update pre-commit hooks to explicitly check for this requirement

- Restructure pre-commit and linting configuration:
  - Move .pydocstyle.ini, .flake8, and pyproject.toml to the root
  - Update pre-commit hooks to reference these configs in the new structure

- Modify tox.ini to prevent packaging errors and improve workflow:
  - Add `skipsdist = True` to disable setuptools packaging
  - Set `usedevelop = False` to prevent unintended package installation
  - Ensure `tox` only runs documentation and linting tasks
  - Aligns with StarlingX repository standards and prevents conflicts
  - Retain the pre-commit/ directory for potential future hooks

- Update documentation and improve contributor guidance:
  - Add CONTRIBUTING.rst with detailed contribution guidelines
  - Create contributors.rst in doc/source for Sphinx-rendered docs
  - Link contributors.rst in index.rst for visibility in generated docs
  - Ensure contributing.rst references the latest CONTRIBUTING.rst
  - Document VSCode and PyCharm auto-doc settings in CONTRIBUTING.rst

This commit ensures consistent docstring enforcement, improves
pre-commit integration, aligns with best practices, and enhances
contributor documentation.

Change-Id: Iba282c20502adb81a7739ec6c3ed8b6f3bc45077
Signed-off-by: Andrew Vaillancourt <andrew.vaillancourt@windriver.com>
2025-02-18 14:35:58 -05:00

1.1 KiB
Raw Blame History

StarlingX Test Documentation

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.

For more information about StarlingX, see the official documentation:

🔗 StarlingX Documentation

Repository Structure

The StarlingX Test Repository Structure provides an overview of key directories and their purpose within the automation framework.

directory_structure

Contribution Guide

For full contribution guidelines, including coding standards, pre-commit hooks, and best practices, see:

contributing

Links