{"id":8123,"library":"doc-warden","title":"Doc-Warden","description":"Doc-Warden is an internal project developed by the Azure SDK Team (current version 0.7.3). It is primarily a command-line tool used in CI builds to enforce documentation standards, specifically for READMEs and Changelogs, across Azure SDK repositories. Its release cadence is irregular, driven by the needs and development cycle of the broader Azure SDK Tools project.","status":"active","version":"0.7.3","language":"en","source_language":"en","source_url":"https://github.com/Azure/azure-sdk-tools/tree/main/packages/python-packages/doc-warden","tags":["documentation","linting","CI/CD","Azure","SDK","build-tools"],"install":[{"cmd":"pip install doc-warden","lang":"bash","label":"Install latest version"},{"cmd":"python -m ensurepip\npip install setuptools wheel\npip install doc-warden","lang":"bash","label":"Install with prerequisites"}],"dependencies":[{"reason":"Used for schema validation of configuration files (e.g., .docsettings.yml).","package":"jsonschema","optional":false},{"reason":"Required for parsing YAML configuration files (e.g., .docsettings.yml).","package":"PyYAML","optional":false}],"imports":[{"note":"Doc-Warden is primarily a command-line interface tool, executed via the 'ward' command. Direct programmatic imports are rare for typical usage.","symbol":"ward","correct":"ward <command> [options]"}],"quickstart":{"code":"# Assume you have cloned a repository that needs documentation checks\n# and that a .docsettings.yml file is present at its root.\n# For example, let's use a placeholder for $(Build.SourcesDirectory)\nREPO_ROOT=\"/path/to/your/repo\"\n\n# Install Doc-Warden (if not already installed)\n# pip install doc-warden\n\n# Example 1: Scan for Readme and Changelog standards (default .docsettings.yml at root)\nprint(f\"Running doc-warden scan on {REPO_ROOT}...\")\n# In a real CI environment, this would be executed directly\n# import subprocess\n# subprocess.run(['ward', 'scan', '-d', REPO_ROOT], check=True)\nprint(\"ward scan -d $REPO_ROOT\")\n\n# Example 2: Scan with a custom .docsettings.yml path\nDOCSETTINGS_PATH=\"$REPO_ROOT/eng/.docsettings.yml\"\nprint(f\"Running doc-warden scan on {REPO_ROOT} with custom config {DOCSETTINGS_PATH}...\")\n# subprocess.run(['ward', 'scan', '-d', REPO_ROOT, '-c', DOCSETTINGS_PATH], check=True)\nprint(f\"ward scan -d $REPO_ROOT -c {DOCSETTINGS_PATH}\")","lang":"python","description":"This quickstart demonstrates how to use the `ward` command-line tool to perform documentation scans. The tool checks for README and Changelog standards based on a `.docsettings.yml` configuration file. It's designed to be run within a CI/CD pipeline, often targeting the source directory of a repository."},"warnings":[{"fix":"Ensure your environment uses Python 3 (preferably 3.4-3.8, as per historical testing, though newer Python 3 versions generally work).","message":"Doc-Warden transitioned to Python 3-only starting with version 0.7.0. Older Python 2 environments are no longer supported.","severity":"breaking","affected_versions":">=0.7.0"},{"fix":"Thoroughly test your `omitted_paths` configuration. Inspect verbose output (`-v` flag if available, or review logs) to ensure the correct files and directories are being excluded from checks. Refer to the official `azure-sdk-tools` repository for up-to-date `.docsettings.yml` examples.","message":"The `omitted_paths` list in `.docsettings.yml` can be inconsistently applied, leading to unexpected files being scanned or ignored.","severity":"gotcha","affected_versions":"All versions"},{"fix":"For .NET projects, define `package_indexing_traversal_stops` in your `.docsettings.yml` to guide Doc-Warden's directory traversal, as .csproj files are often located differently from their documentation. Without this, indexing may not execute correctly.","message":"When working with .NET repositories, Doc-Warden's readme and changelog discovery logic requires `package_indexing_traversal_stops` to be configured in `.docsettings.yml`.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure Python is correctly installed and that pip is accessible. You can often fix this by running `python -m ensurepip` to install pip, then `python -m pip install --upgrade pip` to ensure it's up-to-date.","cause":"Python's package installer, pip, is not found in the system's PATH or not installed correctly.","error":"pip is an unrecognized command"},{"fix":"Verify Doc-Warden was installed successfully (`pip list | grep doc-warden`). If installed in a virtual environment, ensure the environment is activated. If installed globally, ensure the Python scripts directory (e.g., `~/.local/bin` on Linux, `Scripts` folder in Python install on Windows) is in your system's PATH. You may need to open a new terminal session after installation.","cause":"The `ward` command-line entry point, installed by Doc-Warden, is not in your system's PATH, or the installation was incomplete.","error":"ward: command not found"},{"fix":"Carefully review your `.docsettings.yml` file for correct YAML syntax, paying close attention to indentation, colons, and valid key-value pairs. Use a YAML linter if possible to identify the exact parsing error.","cause":"Your `.docsettings.yml` file contains a syntax error or is malformed, preventing PyYAML from parsing it correctly.","error":"PyYAML.YAMLError: while scanning a simple key"}]}