Doc-Warden

0.7.3 · active · verified Thu Apr 16

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.

Common errors

```
pip is an unrecognized command
```
cause Python's package installer, pip, is not found in the system's PATH or not installed correctly.

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.
```
ward: command not found
```
cause The `ward` command-line entry point, installed by Doc-Warden, is not in your system's PATH, or the installation was incomplete.

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.
```
PyYAML.YAMLError: while scanning a simple key
```
cause Your `.docsettings.yml` file contains a syntax error or is malformed, preventing PyYAML from parsing it correctly.

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.

Warnings

breaking Doc-Warden transitioned to Python 3-only starting with version 0.7.0. Older Python 2 environments are no longer supported.
Fix: Ensure your environment uses Python 3 (preferably 3.4-3.8, as per historical testing, though newer Python 3 versions generally work).
gotcha The `omitted_paths` list in `.docsettings.yml` can be inconsistently applied, leading to unexpected files being scanned or ignored.
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.
gotcha When working with .NET repositories, Doc-Warden's readme and changelog discovery logic requires `package_indexing_traversal_stops` to be configured in `.docsettings.yml`.
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.

Install

pip install doc-warden Install latest version
python -m ensurepip pip install setuptools wheel pip install doc-warden Install with prerequisites

Imports

ward
```
ward <command> [options]
```
Doc-Warden is primarily a command-line interface tool, executed via the 'ward' command. Direct programmatic imports are rare for typical usage.

Quickstart

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.

# Assume you have cloned a repository that needs documentation checks
# and that a .docsettings.yml file is present at its root.
# For example, let's use a placeholder for $(Build.SourcesDirectory)
REPO_ROOT="/path/to/your/repo"

# Install Doc-Warden (if not already installed)
# pip install doc-warden

# Example 1: Scan for Readme and Changelog standards (default .docsettings.yml at root)
print(f"Running doc-warden scan on {REPO_ROOT}...")
# In a real CI environment, this would be executed directly
# import subprocess
# subprocess.run(['ward', 'scan', '-d', REPO_ROOT], check=True)
print("ward scan -d $REPO_ROOT")

# Example 2: Scan with a custom .docsettings.yml path
DOCSETTINGS_PATH="$REPO_ROOT/eng/.docsettings.yml"
print(f"Running doc-warden scan on {REPO_ROOT} with custom config {DOCSETTINGS_PATH}...")
# subprocess.run(['ward', 'scan', '-d', REPO_ROOT, '-c', DOCSETTINGS_PATH], check=True)
print(f"ward scan -d $REPO_ROOT -c {DOCSETTINGS_PATH}")

view raw JSON →