{"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":"python","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,"search_vec":"'0.7.3':19 'across':41 'azur':14,42,60,67 'broader':59 'build':31,70 'build-tool':69 'cadenc':47 'changelog':40 'ci':30 'ci/cd':66 'command':25 'command-lin':24 'current':17 'cycl':56 'develop':11,55 'doc':2,5 'doc-warden':1,4 'document':34,64 'driven':50 'enforc':33 'intern':9 'irregular':49 'line':26 'lint':65 'need':53 'primarili':22 'project':10,63 'readm':38 'releas':46 'repositori':44 'sdk':15,43,61,68 'specif':36 'standard':35 'team':16 'tool':27,62,71 'use':28 'version':18 'warden':3,6","created_at":"2026-04-16T17:00:33.890585+00:00","updated_at":"2026-04-16T17:00:33.890585+00:00","problems":{"verify_error":"no import statement found"},"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.7.3","cli_name":"doc-warden","cli_version":"sh: 1: doc-warden: not found","type":"library","homepage":null,"github":"https://github.com/Azure/azure-sdk-tools","docs":null,"changelog":null,"pypi":"https://pypi.org/project/doc-warden/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["azure","devops","testing"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"skip","verified_at":"2026-06-28","last_verified":"2026-06-28","next_check":"2026-07-05","install_tag":null}}