[Errno 20] Not a directory

[patrickbenkoetter]

If I want to overwrite an existing e.g. README.md ansible-doctor fails with [Errno 20] Not a directory if I specify the filename using the -o, --output OUTPUT_PATH option and I'm not sure if this is a problem of ansible-doctor or me trying to run the program on a Mac.

The problem occurs when I explicitly specify an output filename and run the command:

% ll
total 16
drwxr-xr-x@ 7 p  staff  224 10 Nov. 08:46 .
drwxr-xr-x@ 4 p  staff  128  9 Nov. 15:18 ..
-rw-r--r--@ 1 p  staff   93  9 Nov. 15:18 .ansibledoctor.yml
drwxr-xr-x@ 3 p  staff   96  9 Nov. 15:18 defaults
-rw-r--r--@ 1 p  staff  329  9 Nov. 15:18 HEADER.md
drwxr-xr-x@ 3 p  staff   96  9 Nov. 15:18 meta
drwxr-xr-x@ 3 p  staff   96  9 Nov. 15:18 tasks
% ansible-doctor README.md
2025-11-10 08:46:35 [critical ] Base directory not found       path=/Users/p/Projekte/ansible-doctor/example/other-role/README.md

And the problem occurs when I explicitly specify an output filename and re-run the command:

% ansible-doctor README.md
Traceback (most recent call last):
  File "/Users/p/.local/bin/ansible-doctor", line 7, in <module>
    sys.exit(main())
             ~~~~^^
  File "/Users/p/.local/pipx/venvs/ansible-doctor/lib/python3.14/site-packages/ansibledoctor/cli.py", line 148, in main
    AnsibleDoctor()
    ~~~~~~~~~~~~~^^
  File "/Users/p/.local/pipx/venvs/ansible-doctor/lib/python3.14/site-packages/ansibledoctor/cli.py", line 26, in __init__
    self._execute()
    ~~~~~~~~~~~~~^^
  File "/Users/p/.local/pipx/venvs/ansible-doctor/lib/python3.14/site-packages/ansibledoctor/cli.py", line 127, in _execute
    os.chdir(item)
    ~~~~~~~~^^^^^^
NotADirectoryError: [Errno 20] Not a directory: '/Users/p/Projekte/ansible-doctor/example/other-role/README.md'

This is not the case if I omit the -o option:

% ansible-doctor
2025-11-10 08:35:39 [debug    ] Switch working directory       path=/Users/p/Projekte/ansible-doctor/example/other-role
2025-11-10 08:35:39 [info     ] Lookup config file             path=['/Users/p/Library/Application Support/ansible-doctor/config.yml', '.ansibledoctor', '.ansibledoctor.yml', '.ansibledoctor.yaml']
2025-11-10 08:35:39 [info     ] Ansible role detected          role=other-role
2025-11-10 08:35:39 [debug    ] Lookup role files              path=/Users/p/Projekte/ansible-doctor/example/other-role role=other-role
2025-11-10 08:35:39 [debug    ] Found role file                path=tasks/main.yml role=other-role
2025-11-10 08:35:39 [debug    ] Found role file                path=meta/main.yml role=other-role
2025-11-10 08:35:39 [debug    ] Found role file                path=defaults/main.yml role=other-role
2025-11-10 08:35:39 [info     ] Lookup annotation @meta        role=other-role
2025-11-10 08:35:39 [info     ] Found AnnotationItem(author: value) role=other-role
2025-11-10 08:35:39 [info     ] Lookup annotation @todo        role=other-role
2025-11-10 08:35:39 [info     ] Found AnnotationItem(bug: value) role=other-role
2025-11-10 08:35:39 [info     ] Found AnnotationItem(bug: value) role=other-role
2025-11-10 08:35:39 [info     ] Found AnnotationItem(improvement: value) role=other-role
2025-11-10 08:35:39 [info     ] Found AnnotationItem(default: value) role=other-role
2025-11-10 08:35:39 [info     ] Lookup annotation @var         role=other-role
2025-11-10 08:35:39 [info     ] Found AnnotationItem(other_role_unset: description) role=other-role
2025-11-10 08:35:39 [info     ] Found AnnotationItem(other_role_unset: example) role=other-role
2025-11-10 08:35:39 [info     ] Found AnnotationItem(other_role_bool: example) role=other-role
2025-11-10 08:35:39 [info     ] Found AnnotationItem(other_role_empty_dict: description) role=other-role
2025-11-10 08:35:39 [info     ] Found AnnotationItem(other_role_empty_dict: example) role=other-role
2025-11-10 08:35:39 [info     ] Found AnnotationItem(other_role_dict: example) role=other-role
2025-11-10 08:35:39 [info     ] Found AnnotationItem(other_role_undefined_var: description) role=other-role
2025-11-10 08:35:39 [info     ] Found AnnotationItem(other_role_undefined_var: value) role=other-role
2025-11-10 08:35:39 [info     ] Found AnnotationItem(other_role_other_tags: description) role=other-role
2025-11-10 08:35:39 [info     ] Found AnnotationItem(other_role_other_tags: example) role=other-role
2025-11-10 08:35:39 [info     ] Found AnnotationItem(other_role_other_tags: value) role=other-role
2025-11-10 08:35:39 [info     ] Found AnnotationItem(other_role_override: value) role=other-role
2025-11-10 08:35:39 [info     ] Found AnnotationItem(other_role_override_complex: value) role=other-role
2025-11-10 08:35:39 [info     ] Found AnnotationItem(other_role_deprecated: deprecated) role=other-role
2025-11-10 08:35:39 [info     ] Found AnnotationItem(other_role_deprecated_info: deprecated) role=other-role
2025-11-10 08:35:39 [info     ] Found AnnotationItem(other_role_deprecated_info: type) role=other-role
2025-11-10 08:35:39 [info     ] Found AnnotationItem(other_role_multiline_type: type) role=other-role
2025-11-10 08:35:39 [info     ] Lookup annotation @example     role=other-role
2025-11-10 08:35:39 [info     ] Lookup annotation @tag         role=other-role
2025-11-10 08:35:39 [info     ] Lookup template files          role=other-role src=local>/Users/p/.local/pipx/venvs/ansible-doctor/lib/python3.14/site-packages/ansibledoctor/templates
2025-11-10 08:35:39 [debug    ] Skipped template file          path=_toc.j2 role=other-role
2025-11-10 08:35:39 [debug    ] Skipped template file          path=_vars.j2 role=other-role
2025-11-10 08:35:39 [debug    ] Skipped template file          path=_vars_tabulated.j2 role=other-role
2025-11-10 08:35:39 [debug    ] Skipped template file          path=_requirements.j2 role=other-role
2025-11-10 08:35:39 [debug    ] Skipped template file          path=_meta.j2 role=other-role
2025-11-10 08:35:39 [debug    ] Skipped template file          path=_todo.j2 role=other-role
2025-11-10 08:35:39 [debug    ] Skipped template file          path=_tag.j2 role=other-role
2025-11-10 08:35:39 [debug    ] Found template file            path=README.md.j2 role=other-role
These files will be overwritten:
... ./README.md
Do you want to continue? [Y/n] y
2025-11-10 08:35:40 [debug    ] Writing renderer output        path=./README.md role=other-role src=/Users/p/.local/pipx/venvs/ansible-doctor/lib/python3.14/site-packages/ansibledoctor/templates/readme

I work on a Mac (Version 26, tahoe) and I installed ansible-doctor using pipx. My python is /opt/homebrew/bin/python3.14.

[xoxys]

I'm a bit confused by your output. You said

if I specify the filename using the -o, --output OUTPUT_PATH

but in your examples you dont use -o but pass README.md directly to ansible-doctor effectively using it as positional argument base_dir, see the help output

❯ poetry run ansible-doctor --help
usage: ansible-doctor [-h] [-c CONFIG_FILE] [-o OUTPUT_PATH] [-r] [-f] [-d] [-n] [-v] [-q] [--version] [base_dir]

Generate documentation from annotated Ansible roles using templates

positional arguments:
  base_dir              base directory (default: current working directory)

options:
  -h, --help            show this help message and exit
  -c CONFIG_FILE, --config CONFIG_FILE
                        path to configuration file
  -o OUTPUT_PATH, --output OUTPUT_PATH
                        output file or directory
  -r, --recursive       run recursively over the base directory
  -f, --force           force overwrite output file
  -d, --dry-run         dry run without writing
  -n, --no-role-detection
                        disable automatic role detection
  -v                    increase log level
  -q                    decrease log level
  --version             show program's version number and exit

So the correct usage would be :

# from within your role dir
$ ansible-doctor
# or
$ ansible-doctor -o ./README.md
# or
$ ansible-doctor -o ./OTHER_FILE.md

# from outside of your role dir
ansible-doctor example/other-role
# or
ansible-doctor example/other-role -o ./README.md 
# or
ansible-doctor example/other-role -o /tmp/README.md 

Keep in mind as long as OUTPUT_PATH is a relative path, it's treated relative to the detected role dir not the current working dir.