starlingx/test
Code Issues Proposed changes

Enforce docstring standards and update pre-commit

Browse Source 
- 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>
This commit is contained in:
Andrew Vaillancourt
2025-02-11 15:48:04 -05:00
parent 5e9caa16e1
commit 1b9396a2c6
11 changed files with 451 additions and 76 deletions
Download Patch File Download Diff File Expand all files Collapse all files

7
pre-commit/.flake8 → .flake8
View File

@@ -1,7 +1,7 @@
[flake8] [flake8]
max-line-length = 200
max-doc-length = 200 max-doc-length = 200
ignore = E203, E266, E501, W503, W605 ignore = E203, E266, E501, W503, W605, DOC301
disable-docstring-checking = true
# Error Codes # Error Codes
# https://pep8.readthedocs.io/en/release-1.7.x/intro.html#error-codes # https://pep8.readthedocs.io/en/release-1.7.x/intro.html#error-codes
@@ -9,4 +9,5 @@ ignore = E203, E266, E501, W503, W605
# E266 - too many leading ‘#’ for block comment # E266 - too many leading ‘#’ for block comment
# E501 - line too long # E501 - line too long
# W503 - line break before binary operator # W503 - line break before binary operator
# W605 - invalid escape sequence-- need for regular expression # W605 - invalid escape sequence-- needed for regular expressions
# DOC301 - Allows `__init__()` to have its own docstring instead of forcing it to be merged with the class docstring

82
.pre-commit-config.yaml
View File

@@ -1,32 +1,74 @@
--- # -----------------------------------------------------------------------------
# Pre-Commit Hook Configuration for starlingx/test
#
# This configuration ensures code quality by enforcing formatting, style, and
# documentation standards before commits. The following tools are used:
#
# - `isort` → Sorts and organizes imports.
# - `black` → Formats Python code to maintain consistent style.
# - `flake8` → Runs linting checks for Python code style and errors.
# - `pydocstyle` → Enforces PEP 257 and Google-style docstring conventions.
# - `pydoclint` → Validates that docstrings match function signatures.
# - `interrogate` → Ensures all public functions and classes have docstrings.
#
# Notes:
# - `interrogate` is configured to ignore nested functions (`--ignore-nested-functions`)
# to avoid unnecessary enforcement on pytest teardowns and small helper functions.
# - `black` uses `pyproject.toml` for consistency across formatting tools.
# - `pydocstyle` and `pydoclint` ensure compliance with Google-style docstrings.
# -----------------------------------------------------------------------------
default_stages: [commit] default_stages: [commit]
default_language_version: default_language_version:
python: python3.11 python: python3.11
repos: repos:
- repo: local - repo: local
hooks: hooks:
- id: flake8
name: flake8 - code lint and style checks
entry: flake8
language: python
types: [python]
args: [--config, pre-commit/.flake8]
- id: isort - id: isort
name: isort - import sorting name: isort - import sorting
entry: isort entry: isort
language: python language: python
types: [python] types: [python]
args: [--settings-path, pre-commit/pyproject.toml] args: [--settings-path, pyproject.toml]
- id: black
name: black - check formatting (show diff on FAIL)
entry: black
language: python
types: [python]
args: [--config, pre-commit/pyproject.toml, --check, --diff, --color, --quiet]
- id: black
name: black - auto-format code on FAIL
entry: black
language: python
types: [python]
args: [--config, pre-commit/pyproject.toml]
- id: black
name: black - fail if formatting needed
entry: black
language: python
types: [python]
args: [--config, pyproject.toml, --check]
- id: black
name: black - auto-format code
entry: black
language: python
types: [python]
args: [--config, pyproject.toml]
- id: flake8
name: flake8 - code lint and style checks
entry: flake8
language: python
types: [python]
args: [--config=.flake8]
- id: pydocstyle
name: pydocstyle - enforce PEP 257 and Google-style docstrings
entry: pydocstyle
language: python
types: [python]
args: [--config=pydocstyle.ini]
- id: pydoclint
name: pydoclint - enforce Google-style docstring structure
entry: pydoclint
language: python
types: [python]
args: ["--config=pyproject.toml"]
- id: interrogate
name: interrogate - ensure all functions and classes have docstrings
entry: interrogate
language: python
types: [python]
args: ["--fail-under", "100", "--ignore-module", "--ignore-init-method", "--ignore-nested-functions", "--verbose"]

223
CONTRIBUTING.rst Normal file
View File

@@ -0,0 +1,223 @@
========================================
Contributing to the StarlingX Test Repo
========================================
This document outlines the contribution guidelines for the `starlingx/test` repository.
StarlingX Test is an open-source project, and we welcome contributions from the community.
This guide explains the requirements for code contributions, pre-commit checks, and documentation compliance.
1. Setting Up Your Development Environment
==========================================
1.1 Clone the Repository
------------------------
First, clone the repository and set up your environment:
.. code-block:: bash
git clone https://opendev.org/starlingx/test.git
cd test
1.2 Install Dependencies
------------------------
Ensure you have **Python 3.11** installed, then install dependencies using `pipenv`:
.. code-block:: bash
pip install --user pipenv
pipenv install --dev
1.3 Enable Pre-Commit Hooks
---------------------------
Pre-commit hooks are required to ensure code formatting and docstring compliance:
.. code-block:: bash
pre-commit install
Once installed, **pre-commit will automatically run** on every commit.
2. Code Contribution Guidelines
===============================
2.1 Code Style
--------------
- Python code must be formatted with ``black`` and ``isort``.
- Line length should not exceed 200 characters.
- Use **f-strings** instead of ``%`` formatting or ``.format()``.
2.2 Docstring Standards
-----------------------
All docstrings should follow the **Google Python Style Guide** and must be formatted consistently to pass pre-commit checks.
- **Google-style docstrings** are required for all **functions and classes**, with the following exceptions:
- **Module-level docstrings** are **not required** or enforced by pre-commit hooks.
However, they are **recommended** for utility scripts and config files to clarify their intended use for other developers.
- ``__init__`` methods are **allowed** to have docstrings but are **not required**.
If a docstring is present, it should describe the purpose of the constructor and any initialization logic.
The pre-commit hooks automatically enforce **PEP 257** and **Google-style docstrings** using ``pydocstyle``, ``pydoclint``, and ``interrogate``.
For auto-generating docstrings that align with these standards, see: :ref:`auto-docstrings`.
2.3 Type Hinting
----------------
All function signatures must include **type hints** for arguments and return values.
**Example (Required Formatting):**
.. code-block:: python
def add(a: int, b: int) -> int:
"""
Adds two numbers.
Args:
a (int): The first number.
b (int): The second number.
Returns:
int: The sum of `a` and `b`.
"""
return a + b
3. Pre-Commit Hooks & Linting
=============================
This repository uses **pre-commit hooks** to enforce formatting, linting, and docstring compliance.
3.1 Installed Pre-Commit Hooks
------------------------------
The following tools are run automatically on every commit:
- **black**: Enforces PEP 8-compliant code formatting.
- **isort**: Ensures import statements are correctly ordered.
- **flake8**: Static code analysis and linting.
- **pydocstyle**: Enforces PEP 257 and Google-style docstring formatting.
- **pydoclint**: Ensures function signatures and docstrings match.
- **interrogate**: Ensures all functions and classes have docstrings.
3.2 Running Pre-Commit Hooks Manually
-------------------------------------
You can run pre-commit checks manually before committing:
.. code-block:: bash
pre-commit run --all-files
4. Handling Return Types in Docstrings & Type Hints
===================================================
4.1 Why Are Return Types Required in Both Docstrings and Type Hints?
--------------------------------------------------------------------
We enforce **return type hints** (e.g., ``-> type``) and **docstring return types** (e.g., ``Returns:`` section) **to ensure consistency**.
**Why is this required?**
- Ensures clarity in documentation.
- Helps enforce consistency across the project.
- Required by pre-commit hooks (`pydocstyle`, `pydoclint`, `interrogate`).
4.2 Example of Correct Formatting
---------------------------------
**Correct Example:**
.. code-block:: python
def multiply(a: int, b: int) -> int:
"""
Multiplies two integers.
Args:
a (int): The first integer.
b (int): The second integer.
Returns:
int: The product of `a` and `b`.
"""
return a * b
**Incorrect Example (Missing `Returns:` section):**
.. code-block:: python
def multiply(a: int, b: int) -> int:
"""Multiplies two integers."""
return a * b # Missing `Returns:` section in docstring.
.. _auto-docstrings:
5. Auto-Generating Docstrings in VSCode & PyCharm
=================================================
To simplify docstring compliance, you can use IDE plugins.
5.1 VSCode: Auto-Generating Docstrings
--------------------------------------
1. Install the [Python Docstring Generator](https://marketplace.visualstudio.com/items?itemName=njpwerner.autodocstring).
2. Configure VSCode to generate **Google-style docstrings** that align with pre-commit checks.
Add the following settings to your ``settings.json``:
.. code-block:: json
{
"autoDocstring.docstringFormat": "google",
"autoDocstring.includeName": true,
"autoDocstring.includeExtendedSummary": true,
"autoDocstring.guessTypes": true,
"autoDocstring.startOnNewLine": true,
"autoDocstring.quoteStyle": "\"\"\"",
"autoDocstring.generateDocstringOnEnter": true
}
3. Save the file and restart VSCode.
5.2 PyCharm: Auto-Generating Docstrings
---------------------------------------
1. Open **PyCharm**.
2. Go to **File → Settings → Tools → Python Integrated Tools**.
3. Find the **Docstring format** dropdown and select **Google**.
4. Click **Apply** and **OK**.
6. References
=============
- `OpenStack Contributor Guide <https://docs.openstack.org/contributors/en_GB/common/setup-gerrit.html>`_
- `OpenStack Individual Contributor License Agreement (ICLA) <https://review.opendev.org/settings/new-agreement>`_
- `OpenDev Developer Documentation <https://docs.opendev.org/opendev/infra-manual/latest/developers.html>`_
- `StarlingX Contributor Guidelines <https://docs.starlingx.io/contributor/index.html>`_
- `StarlingX Code Submission Guide <https://docs.starlingx.io/developer_resources/code-submission-guide.html>`_
- `How to Contribute to StarlingX (YouTube) <https://www.youtube.com/watch?v=oHmx0M3cYlE>`_
- `OpenStack Git Commit Message Guidelines <https://wiki.openstack.org/wiki/GitCommitMessages>`_
- `Google Python Style Guide <https://google.github.io/styleguide/pyguide.html#381-docstrings>`_
- `PEP 257 (Docstring Conventions) <https://peps.python.org/pep-0257/>`_
- `PEP 484 (Type Hints) <https://peps.python.org/pep-0484/>`_
- `PEP 498 (f-Strings) <https://peps.python.org/pep-0498/>`_
- `pydocstyle Documentation <https://www.pydocstyle.org/en/latest/>`_
- `pydoclint Documentation <https://github.com/jsh9/pydoclint>`_
- `interrogate Documentation <https://interrogate.readthedocs.io/en/latest/>`_
- `pre-commit <https://pre-commit.com/>`_
- `black <https://black.readthedocs.io/en/stable/>`_
- `isort <https://pycqa.github.io/isort/>`_
- `flake8 <https://flake8.pycqa.org/en/latest/>`_
- `AutoDocstring for VSCode <https://github.com/autosoft-dev/autoDocstring>`_
- `VSCode: Auto-Generating Docstrings <https://code.visualstudio.com/docs/python/editing#_auto-generating-docstrings>`_
- `PyCharm: Creating Documentation Comments <https://www.jetbrains.com/help/pycharm/creating-documentation-comments.html>`_

5
Pipfile
View File

@@ -13,6 +13,11 @@ black = "==24.3.0"
isort = "==5.13.2" isort = "==5.13.2"
flake8 = "==7.0.0" flake8 = "==7.0.0"
# Docstring Compliance and Enforcement
pydocstyle = "==6.3.0" # Enforce PEP 257 and Google-style docstrings
pydoclint = "==0.4.1" # Validate function signatures match docstrings (Google-style)
interrogate = "==1.5.0" # Ensure all functions and classes have docstrings
# Tools Packages # Tools Packages
pytest = "==8.1.1" pytest = "==8.1.1"
paramiko = "==3.4.0" paramiko = "==3.4.0"

133
Pipfile.lock generated
View File

@@ -1,7 +1,7 @@
{ {
"_meta": { "_meta": {
"hash": { "hash": {
"sha256": "9301571a01a6b76d26e670a5f0fb8a5d597adc4ca6877f29f29d2ad7c241747d" "sha256": "91b3ddf1a01a08c3c3b52dd48e801b3155f312616b504656e841ae451d5b7616"
}, },
"pipfile-spec": 6, "pipfile-spec": 6,
"requires": { "requires": {
@@ -313,36 +313,40 @@
}, },
"cryptography": { "cryptography": {
"hashes": [ "hashes": [
"sha256:1923cb251c04be85eec9fda837661c67c1049063305d6be5721643c22dd4e2b7", "sha256:00918d859aa4e57db8299607086f793fa7813ae2ff5a4637e318a25ef82730f7",
"sha256:37d76e6863da3774cd9db5b409a9ecfd2c71c981c38788d3fcfaf177f447b731", "sha256:1e8d181e90a777b63f3f0caa836844a1182f1f265687fac2115fcf245f5fbec3",
"sha256:3c672a53c0fb4725a29c303be906d3c1fa99c32f58abe008a82705f9ee96f40b", "sha256:1f9a92144fa0c877117e9748c74501bea842f93d21ee00b0cf922846d9d0b183",
"sha256:404fdc66ee5f83a1388be54300ae978b2efd538018de18556dde92575e05defc", "sha256:21377472ca4ada2906bc313168c9dc7b1d7ca417b63c1c3011d0c74b7de9ae69",
"sha256:4ac4c9f37eba52cb6fbeaf5b59c152ea976726b865bd4cf87883a7e7006cc543", "sha256:24979e9f2040c953a94bf3c6782e67795a4c260734e5264dceea65c8f4bae64a",
"sha256:62901fb618f74d7d81bf408c8719e9ec14d863086efe4185afd07c352aee1d2c", "sha256:2a46a89ad3e6176223b632056f321bc7de36b9f9b93b2cc1cccf935a3849dc62",
"sha256:660cb7312a08bc38be15b696462fa7cc7cd85c3ed9c576e81f4dc4d8b2b31591", "sha256:322eb03ecc62784536bc173f1483e76747aafeb69c8728df48537eb431cd1911",
"sha256:708ee5f1bafe76d041b53a4f95eb28cdeb8d18da17e597d46d7833ee59b97ede", "sha256:436df4f203482f41aad60ed1813811ac4ab102765ecae7a2bbb1dbb66dcff5a7",
"sha256:761817a3377ef15ac23cd7834715081791d4ec77f9297ee694ca1ee9c2c7e5eb", "sha256:4f422e8c6a28cf8b7f883eb790695d6d45b0c385a2583073f3cec434cc705e1a",
"sha256:831c3c4d0774e488fdc83a1923b49b9957d33287de923d58ebd3cec47a0ae43f", "sha256:53f23339864b617a3dfc2b0ac8d5c432625c80014c25caac9082314e9de56f41",
"sha256:84111ad4ff3f6253820e6d3e58be2cc2a00adb29335d4cacb5ab4d4d34f2a123", "sha256:5fed5cd6102bb4eb843e3315d2bf25fede494509bddadb81e03a859c1bc17b83",
"sha256:8b3e6eae66cf54701ee7d9c83c30ac0a1e3fa17be486033000f2a73a12ab507c", "sha256:610a83540765a8d8ce0f351ce42e26e53e1f774a6efb71eb1b41eb01d01c3d12",
"sha256:9e6fc8a08e116fb7c7dd1f040074c9d7b51d74a8ea40d4df2fc7aa08b76b9e6c", "sha256:6c8acf6f3d1f47acb2248ec3ea261171a671f3d9428e34ad0357148d492c7864",
"sha256:a01956ddfa0a6790d594f5b34fc1bfa6098aca434696a03cfdbe469b8ed79285", "sha256:6f76fdd6fd048576a04c5210d53aa04ca34d2ed63336d4abd306d0cbe298fddf",
"sha256:abc998e0c0eee3c8a1904221d3f67dcfa76422b23620173e28c11d3e626c21bd", "sha256:72198e2b5925155497a5a3e8c216c7fb3e64c16ccee11f0e7da272fa93b35c4c",
"sha256:b15492a11f9e1b62ba9d73c210e2416724633167de94607ec6069ef724fad092", "sha256:887143b9ff6bad2b7570da75a7fe8bbf5f65276365ac259a5d2d5147a73775f2",
"sha256:be4ce505894d15d5c5037167ffb7f0ae90b7be6f2a98f9a5c3442395501c32fa", "sha256:888fcc3fce0c888785a4876ca55f9f43787f4c5c1cc1e2e0da71ad481ff82c5b",
"sha256:c5eb858beed7835e5ad1faba59e865109f3e52b3783b9ac21e7e47dc5554e289", "sha256:8e6a85a93d0642bd774460a86513c5d9d80b5c002ca9693e63f6e540f1815ed0",
"sha256:cd4e834f340b4293430701e772ec543b0fbe6c2dea510a5286fe0acabe153a02", "sha256:94f99f2b943b354a5b6307d7e8d19f5c423a794462bde2bf310c770ba052b1c4",
"sha256:d2436114e46b36d00f8b72ff57e598978b37399d2786fd39793c36c6d5cb1c64", "sha256:9b336599e2cb77b1008cb2ac264b290803ec5e8e89d618a5e978ff5eb6f715d9",
"sha256:eb33480f1bad5b78233b0ad3e1b0be21e8ef1da745d8d2aecbb20671658b9053", "sha256:a2d8a7045e1ab9b9f803f0d9531ead85f90c5f2859e653b61497228b18452008",
"sha256:eca27345e1214d1b9f9490d200f9db5a874479be914199194e746c893788d417", "sha256:b8272f257cf1cbd3f2e120f14c68bff2b6bdfcc157fafdee84a1b795efd72862",
"sha256:ed3534eb1090483c96178fcb0f8893719d96d5274dfde98aa6add34614e97c8e", "sha256:bf688f615c29bfe9dfc44312ca470989279f0e94bb9f631f85e3459af8efc009",
"sha256:f3f6fdfa89ee2d9d496e2c087cebef9d4fcbb0ad63c40e821b39f74bf48d9c5e", "sha256:d9c5b9f698a83c8bd71e0f4d3f9f839ef244798e5ffe96febfa9714717db7af7",
"sha256:f53c2c87e0fb4b0c00fa9571082a057e37690a8f12233306161c8f4b819960b7", "sha256:dd7c7e2d71d908dc0f8d2027e1604102140d84b155e658c20e8ad1304317691f",
"sha256:f5e7cb1e5e56ca0933b4873c0220a78b773b24d40d186b6738080b73d3d0a756", "sha256:df978682c1504fc93b3209de21aeabf2375cb1571d4e61907b3e7a2540e83026",
"sha256:f677e1268c4e23420c3acade68fac427fffcb8d19d7df95ed7ad17cdef8404f4" "sha256:e403f7f766ded778ecdb790da786b418a9f2394f36e8cc8b796cc056ab05f44f",
"sha256:eb3889330f2a4a148abead555399ec9a32b13b7c8ba969b72d8e500eb7ef84cd",
"sha256:f4daefc971c2d1f82f03097dc6f216744a6cd2ac0f04c68fb935ea2ba2a0d420",
"sha256:f51f5705ab27898afda1aaa430f34ad90dc117421057782022edf0600bec5f14",
"sha256:fd0ee90072861e276b0ff08bd627abec29e32a53b2be44e41dbcdf87cbee2b00"
], ],
"markers": "python_version >= '3.7' and python_full_version not in '3.9.0, 3.9.1'", "markers": "python_version >= '3.7' and python_full_version not in '3.9.0, 3.9.1'",
"version": "==44.0.0" "version": "==44.0.1"
}, },
"distlib": { "distlib": {
"hashes": [ "hashes": [
@@ -360,6 +364,14 @@
"markers": "python_version >= '3.10'", "markers": "python_version >= '3.10'",
"version": "==5.0.6" "version": "==5.0.6"
}, },
"docstring-parser-fork": {
"hashes": [
"sha256:55d7cbbc8b367655efd64372b9a0b33a49bae930a8ddd5cdc4c6112312e28a87",
"sha256:b44c5e0be64ae80f395385f01497d381bd094a57221fd9ff020987d06857b2a0"
],
"markers": "python_version >= '3.7' and python_version < '4.0'",
"version": "==0.0.12"
},
"docutils": { "docutils": {
"hashes": [ "hashes": [
"sha256:3a6b18732edf182daa3cd12775bbb338cf5691468f91eeeb109deff6ebfa986f", "sha256:3a6b18732edf182daa3cd12775bbb338cf5691468f91eeeb109deff6ebfa986f",
@@ -443,11 +455,11 @@
}, },
"identify": { "identify": {
"hashes": [ "hashes": [
"sha256:7bec12768ed44ea4761efb47806f0a41f86e7c0a5fdf5950d4648c90eca7e251", "sha256:155931cb617a401807b09ecec6635d6c692d180090a1cedca8ef7d58ba5b6aa0",
"sha256:cbd1810bce79f8b671ecb20f53ee0ae8e86ae84b557de31d89709dc2a48ba881" "sha256:3fa266b42eba321ee0b2bb0936a6a6b9e36a1351cbb69055b3082f4193035684"
], ],
"markers": "python_version >= '3.9'", "markers": "python_version >= '3.9'",
"version": "==2.6.6" "version": "==2.6.7"
}, },
"idna": { "idna": {
"hashes": [ "hashes": [
@@ -473,6 +485,15 @@
"markers": "python_version >= '3.7'", "markers": "python_version >= '3.7'",
"version": "==2.0.0" "version": "==2.0.0"
}, },
"interrogate": {
"hashes": [
"sha256:a4ccc5cbd727c74acc98dee6f5e79ef264c0bcfa66b68d4e123069b2af89091a",
"sha256:b6f325f0aa84ac3ac6779d8708264d366102226c5af7d69058cecffcff7a6d6c"
],
"index": "pypi",
"markers": "python_version >= '3.6'",
"version": "==1.5.0"
},
"isort": { "isort": {
"hashes": [ "hashes": [
"sha256:48fdfcb9face5d58a4f6dde2e72a1fb8dcaf8ab26f95ab49fab84c2ddefb0109", "sha256:48fdfcb9face5d58a4f6dde2e72a1fb8dcaf8ab26f95ab49fab84c2ddefb0109",
@@ -753,6 +774,14 @@
"markers": "python_version >= '3.7'", "markers": "python_version >= '3.7'",
"version": "==2.9.9" "version": "==2.9.9"
}, },
"py": {
"hashes": [
"sha256:51c75c4126074b472f746a24399ad32f6053d1b34b68d2fa41e558e6f4a98719",
"sha256:607c53218732647dff4acdfcd50cb62615cedf612e72d1724fb1a0cc6405b378"
],
"markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'",
"version": "==1.11.0"
},
"pycodestyle": { "pycodestyle": {
"hashes": [ "hashes": [
"sha256:41ba0e7afc9752dfb53ced5489e89f8186be00e599e712660695b7a75ff2663f", "sha256:41ba0e7afc9752dfb53ced5489e89f8186be00e599e712660695b7a75ff2663f",
@@ -769,6 +798,24 @@
"markers": "python_version >= '3.8'", "markers": "python_version >= '3.8'",
"version": "==2.22" "version": "==2.22"
}, },
"pydoclint": {
"hashes": [
"sha256:4e32fdf0a47a2199377617f09af0a82a2157f80543026f919a17112a396e752f",
"sha256:d39ed26a793203afadb1917011710fbf258ac3dddcd79b53212e0a2107221643"
],
"index": "pypi",
"markers": "python_version >= '3.8'",
"version": "==0.4.1"
},
"pydocstyle": {
"hashes": [
"sha256:118762d452a49d6b05e194ef344a55822987a462831ade91ec5c06fd2169d019",
"sha256:7ce43f0c0ac87b07494eb9c0b462c0b73e6ff276807f204d6b53edc72b7e44e1"
],
"index": "pypi",
"markers": "python_version >= '3.6'",
"version": "==6.3.0"
},
"pyflakes": { "pyflakes": {
"hashes": [ "hashes": [
"sha256:1c61603ff154621fb2a9172037d84dca3500def8c8b630657d1701f026f8af3f", "sha256:1c61603ff154621fb2a9172037d84dca3500def8c8b630657d1701f026f8af3f",
@@ -1008,6 +1055,22 @@
"markers": "python_version >= '3.8'", "markers": "python_version >= '3.8'",
"version": "==0.5.3" "version": "==0.5.3"
}, },
"tabulate": {
"hashes": [
"sha256:0095b12bf5966de529c0feb1fa08671671b3368eec77d7ef7ab114be2c068b3c",
"sha256:024ca478df22e9340661486f85298cff5f6dcdba14f3813e8830015b9ed1948f"
],
"markers": "python_version >= '3.7'",
"version": "==0.9.0"
},
"toml": {
"hashes": [
"sha256:806143ae5bfb6a3c6e736a764057db0e6a0e05e338b5630894a5f779cabb4f9b",
"sha256:b3bda1d108d5dd99f4a20d24d9c348e91c4db7ab1b749200bded2f839ccbe68f"
],
"markers": "python_version >= '2.6' and python_version not in '3.0, 3.1, 3.2'",
"version": "==0.10.2"
},
"tornado": { "tornado": {
"hashes": [ "hashes": [
"sha256:072ce12ada169c5b00b7d92a99ba089447ccc993ea2143c9ede887e0937aa803", "sha256:072ce12ada169c5b00b7d92a99ba089447ccc993ea2143c9ede887e0937aa803",
@@ -1062,11 +1125,11 @@
}, },
"virtualenv": { "virtualenv": {
"hashes": [ "hashes": [
"sha256:4e4cb403c0b0da39e13b46b1b2476e505cb0046b25f242bee80f62bf990b2779", "sha256:fdaabebf6d03b5ba83ae0a02cfe96f48a716f4fae556461d180825866f75b728",
"sha256:b8b8970138d32fb606192cb97f6cd4bb644fa486be9308fb9b63f81091b5dc35" "sha256:febddfc3d1ea571bdb1dc0f98d7b45d24def7428214d4fb73cc486c9568cce6a"
], ],
"markers": "python_version >= '3.8'", "markers": "python_version >= '3.8'",
"version": "==20.29.1" "version": "==20.29.2"
}, },
"wsproto": { "wsproto": {
"hashes": [ "hashes": [

28
README.rst
View File

@@ -171,10 +171,7 @@ Contribution
------------ ------------
2. **Coding Standards**: 2. **Coding Standards**:
- Ensure your code adheres to project conventions. While more detailed best practices are being refined and will be provided in future updates, the following standards are currently enforced: - Ensure your code adheres to project conventions. For detailed guidelines, see `CONTRIBUTING.rst`.
- Use `Google style, PEP-compliant docstrings <https://google.github.io/styleguide/pyguide.html#381-docstrings>`_ for every function and module. These docstrings should align with the principles outlined in `PEP 257 (Docstring Conventions) <https://peps.python.org/pep-0257/>`_. Tools for auto-generating these docstrings are available in IDEs such as `VSCode <https://code.visualstudio.com/docs/python/editing#_auto-generating-docstrings>`_ and `PyCharm <https://www.jetbrains.com/help/pycharm/creating-documentation-comments.html>`_.
- Include `type hints <https://peps.python.org/pep-0484/>`_ for all function arguments and return types.
- Use `f-strings <https://peps.python.org/pep-0498/>`_ for string formatting.
- Pre-commit hooks will run automatically on every commit once installed to ensure formatting and linting. - Pre-commit hooks will run automatically on every commit once installed to ensure formatting and linting.
- **Tools Enforced by Pre-Commit Hooks**: - **Tools Enforced by Pre-Commit Hooks**:
@@ -182,6 +179,9 @@ Contribution
- `black <https://black.readthedocs.io/en/stable/>`_ - `black <https://black.readthedocs.io/en/stable/>`_
- `isort <https://pycqa.github.io/isort/>`_ - `isort <https://pycqa.github.io/isort/>`_
- `flake8 <https://flake8.pycqa.org/en/latest/>`_ - `flake8 <https://flake8.pycqa.org/en/latest/>`_
- `pydocstyle <https://www.pydocstyle.org/en/latest/>`_
- `pydoclint <https://github.com/jsh9/pydoclint>`_
- `interrogate <https://interrogate.readthedocs.io/en/latest/>`_
3. **Submitting Changes**: 3. **Submitting Changes**:
- Ensure your commit messages adhere to the guidelines in the - Ensure your commit messages adhere to the guidelines in the
@@ -193,8 +193,8 @@ Contribution
git commit -s # include sign-off git commit -s # include sign-off
git review git review
References 6. References
---------- =============
- `OpenStack Contributor Guide <https://docs.openstack.org/contributors/en_GB/common/setup-gerrit.html>`_ - `OpenStack Contributor Guide <https://docs.openstack.org/contributors/en_GB/common/setup-gerrit.html>`_
- `OpenStack Individual Contributor License Agreement (ICLA) <https://review.opendev.org/settings/new-agreement>`_ - `OpenStack Individual Contributor License Agreement (ICLA) <https://review.opendev.org/settings/new-agreement>`_
@@ -203,13 +203,17 @@ References
- `StarlingX Code Submission Guide <https://docs.starlingx.io/developer_resources/code-submission-guide.html>`_ - `StarlingX Code Submission Guide <https://docs.starlingx.io/developer_resources/code-submission-guide.html>`_
- `How to Contribute to StarlingX (YouTube) <https://www.youtube.com/watch?v=oHmx0M3cYlE>`_ - `How to Contribute to StarlingX (YouTube) <https://www.youtube.com/watch?v=oHmx0M3cYlE>`_
- `OpenStack Git Commit Message Guidelines <https://wiki.openstack.org/wiki/GitCommitMessages>`_ - `OpenStack Git Commit Message Guidelines <https://wiki.openstack.org/wiki/GitCommitMessages>`_
- `Google Style Python Docstrings <https://google.github.io/styleguide/pyguide.html#381-docstrings>`_ - `Google Python Style Guide <https://google.github.io/styleguide/pyguide.html#381-docstrings>`_
- `VSCode: Auto-Generating Docstrings <https://code.visualstudio.com/docs/python/editing#_auto-generating-docstrings>`_ - `PEP 257 (Docstring Conventions) <https://peps.python.org/pep-0257/>`_
- `PyCharm: Creating Documentation Comments <https://www.jetbrains.com/help/pycharm/creating-documentation-comments.html>`_ - `PEP 484 (Type Hints) <https://peps.python.org/pep-0484/>`_
- `PEP 257: Docstring Conventions <https://peps.python.org/pep-0257/>`_ - `PEP 498 (f-Strings) <https://peps.python.org/pep-0498/>`_
- `PEP 484: Type Hints <https://peps.python.org/pep-0484/>`_ - `pydocstyle Documentation <https://www.pydocstyle.org/en/latest/>`_
- `PEP 498: f-Strings <https://peps.python.org/pep-0498/>`_ - `pydoclint Documentation <https://github.com/jsh9/pydoclint>`_
- `interrogate Documentation <https://interrogate.readthedocs.io/en/latest/>`_
- `pre-commit <https://pre-commit.com/>`_ - `pre-commit <https://pre-commit.com/>`_
- `black <https://black.readthedocs.io/en/stable/>`_ - `black <https://black.readthedocs.io/en/stable/>`_
- `isort <https://pycqa.github.io/isort/>`_ - `isort <https://pycqa.github.io/isort/>`_
- `flake8 <https://flake8.pycqa.org/en/latest/>`_ - `flake8 <https://flake8.pycqa.org/en/latest/>`_
- `AutoDocstring for VSCode <https://github.com/autosoft-dev/autoDocstring>`_
- `VSCode: Auto-Generating Docstrings <https://code.visualstudio.com/docs/python/editing#_auto-generating-docstrings>`_
- `PyCharm: Creating Documentation Comments <https://www.jetbrains.com/help/pycharm/creating-documentation-comments.html>`_

9
doc/source/contributing.rst Normal file
View File

@@ -0,0 +1,9 @@
==============================
Contribution Guidelines
==============================
This document provides contribution guidelines for ``starlingx/test``.
For the complete contribution guide, refer to the latest ``CONTRIBUTING.rst`` in the repository root or view it on OpenDev.
🔗 `View CONTRIBUTING.rst on OpenDev <https://opendev.org/starlingx/test/src/branch/master/CONTRIBUTING.rst>`_

19
doc/source/index.rst
View File

@@ -10,7 +10,8 @@ This project contains **Automated Test Cases** that validate the **StarlingX pro
The test framework provides tools and structured test cases to ensure the stability and reliability of StarlingX components. 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: For more information about StarlingX, see the official documentation:
🔗 https://docs.starlingx.io/
🔗 `StarlingX Documentation <https://docs.starlingx.io/>`_
---------------------- ----------------------
Repository Structure Repository Structure
@@ -23,10 +24,20 @@ The **StarlingX Test Repository Structure** provides an overview of key director
directory_structure directory_structure
-------------------
Contribution Guide
-------------------
For full contribution guidelines, including coding standards, pre-commit hooks, and best practices, see:
.. toctree::
:maxdepth: 1
contributing
----- -----
Links Links
----- -----
* **Source Code:** https://opendev.org/starlingx/test - **Source Code:** `StarlingX Test Repository <https://opendev.org/starlingx/test>`_
* **Code Review:** https://review.opendev.org/#/q/project:starlingx/test - **Code Review:** `Gerrit Code Review <https://review.opendev.org/#/q/project:starlingx/test>`_
* **Bug Tracking:** https://storyboard.openstack.org/#!/project/starlingx/test

12
pydocstyle.ini Normal file
View File

@@ -0,0 +1,12 @@
# Enforce Google-style docstrings while avoiding conflicts with pydoclint
[pydocstyle]
convention = google
# Ignored rules:
# D100 - Ignore missing module-level docstrings (unnecessary in structured frameworks)
# D107 - Ignore missing docstrings for __init__ methods (handled by interrogate)
# D200 - Allow multi-line docstrings instead of forcing one-liners (Google-style)
# D203 - Allow class docstrings to be directly under the class definition (Google-style)
# D212 - Allow function/method docstring summaries to start on the second line (Google-style)
# D213 - Allow class docstring summaries to start on the first line (Google-style)
add-ignore = D100,D107,D200,D203,D212,D213

6
pre-commit/pyproject.toml → pyproject.toml
View File

@@ -1,12 +1,14 @@
[tool.isort] [tool.isort]
py_version = "311" py_version = "311"
profile = "black" profile = "black"
line_length = 200
[tool.black] [tool.black]
target-version = ['py311'] target-version = ['py311']
line-length = 200
skip-string-normalization = true skip-string-normalization = true
preview = true preview = true
include = '\.py' include = '\.py'
[tool.pydoclint]
style = "google"
check-return-types = true
allow-init-docstring = true

3
tox.ini
View File

@@ -1,8 +1,10 @@
[tox] [tox]
envlist = py311 envlist = py311
skipsdist = True # Ensures tox does not attempt to package the repository
[testenv:docs] [testenv:docs]
basepython = python3 basepython = python3
usedevelop = False # Prevents installation as a package
deps = -r{toxinidir}/doc/requirements.txt deps = -r{toxinidir}/doc/requirements.txt
commands = commands =
rm -rf doc/build rm -rf doc/build
@@ -11,6 +13,7 @@ allowlist_externals = rm
[testenv:releasenotes] [testenv:releasenotes]
basepython = python3 basepython = python3
usedevelop = False # Ensures tox only runs documentation generation
deps = -r{toxinidir}/doc/requirements.txt deps = -r{toxinidir}/doc/requirements.txt
commands = commands =
rm -rf releasenotes/build rm -rf releasenotes/build