Skip to content

developer_guide.md

Latest commit

 

History

History
130 lines (104 loc) · 6.19 KB

developer_guide.md

File metadata and controls

130 lines (104 loc) · 6.19 KB
Raw

Development

Install development dependencies

From the docs_validator root directory:

python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install -e ".[dev]"

Scenario: developing docs_validator and debugging it against the system located in a sibling directory

Development Iteration

  1. Make changes in ../docs_validator/src/docs_validator/.
  2. Re-run the validation command. Recompilation or pip install is not required.

Check without creating a commit:

bash .githooks/pre-commit

Commit, skip check:

git commit --no-verify

Running Tests

# With coverage
pytest --cov=src/docs_validator --cov-report=term
# Verbose output
pytest tests/unit/ -vv --tb=short

Local Code Validation (pre-commit hook)

The repository uses a native hook to check before committing. The hook blocks the commit if tests fail or coverage is <70%.

chmod +x .githooks/pre-commit
git config core.hooksPath .githooks

Updating Dependencies

In the docs_validator root:

source .venv/bin/activate
pip install -e ".[dev]"

In the tested project:

cd ../project_to_validate/ && source .venv/bin/activate
pip install -e ../docs_validator --upgrade

PyCharm Pytest Configuration

To configure pytest templates in PyCharm:

  • Additional arguments: -vv --tb=short --color=yes --cov=src/docs_validator --cov-report=term -p no:warnings
  • Working directory: $ProjectFileDir$
  • Environment variables: PYTEST_ADDOPTS="-vv --tb=short --color=yes"

Integration Testing Procedure (Example)

To verify the docs_validator's functionality on a real documentation project (e.g., notes_and_thoughts):

  1. Setup: Ensure docs_validator is installed in editable mode with [dev] dependencies in an adjacent directory.
  2. Clone Test Repository: git clone https://gitlab.com/Nokhrin/notes_and_thoughts.git (or any target project).
  3. Run Full Validation: 
    docs_validator scan ../notes_and_thoughts --validate --report html --output /tmp/report.html --log-level info
  4. Analyze Results: Open /tmp/report.html in a browser. Verify sections: Issues Summary, Broken Links, Orphan Files, and Missing Anchors.
  5. Strict Mode (CI Simulation): 
    docs_validator scan ../notes_and_thoughts --validate --fail-on-error
echo "Exit code: $?" # Should be 1 if ERRORs exist, 0 otherwise.
  6. Test Configuration Auto-loading: Create a .docs_validator.toml in the root of notes_and_thoughts and run docs_validator scan without flags to verify settings are applied.

Debugging in PyCharm

Prerequisites

  • The docs_validator project and the tested project (e.g., project_to_validate) are cloned into adjacent directories.
  • The tested project has a virtual environment with docs_validator installed in editable mode.
  • Interpreter (.venv) of project under test is added to PyCharm

Run Configuration for Debugging

  1. Create a new configuration: Run -> Edit Configurations... -> + -> Python

  2. Fill in the parameters:

    Parameter Value
    Python interpreter Interpreter from the tested project's .venv
    Script path $ProjectFileDir$/src/docs_validator/cli.py
    Module name (leave empty)
    Parameters scan ../project_to_validate --validate --log-level debug
    Working directory $ProjectFileDir$/../project_to_validate
    Environment variables PYTHONDONTWRITEBYTECODE=1;PYTHONUNBUFFERED=1

  3. Set breakpoints.

  4. Run Debug.

Test Run Configuration

  1. Create a configuration: Run -> Edit Configurations... -> + -> pytest

  2. Parameters:

    Parameter Value
    Name pytest unit tests
    Target path/to/docs_validator/tests/unit/
    Additional arguments -vv --tb=short --color=yes -s --log-cli-level=DEBUG
    Working directory $ProjectFileDir$
    Environment variables (leave empty)

Technical Nuances and Potential Errors

Scenario Cause Solution
docs_validator: command not found venv is not activated or PATH is not updated Run source .venv/bin/activate or use python -m docs_validator.cli scan .
Settings are read from docs_validator instead of project_to_validate In cli.py, the config is searched in Path.cwd() / ".docs_validator.toml" Run the command from project_to_validate or explicitly specify --config ./docs_validator.toml
Absolute paths are displayed in reports FilesExplorer builds paths relative to root_path Pass a relative path (. or ./docs) to scan, not an absolute one
Dependencies are not resolved pyproject.toml in docs_validator requires networkx The [dev] flag in pip install automatically installs dependencies from dependencies and optional-dependencies