I have recently created a GitHub Actions workflow to lint/reformat the code of my repo and create documentation HTML pages using pdoc. The last step is problematic, because pdoc runs the .py files to create the documentation. For one of the files (file.py) the ServiceNow ODBC driver needs to be set up and it's unfeasible to do on every workflow. That is why I decided to try using pdoc with pre-commit. Locally the pdoc command only works if pdoc is in the same directory as file.py, that is why a virtual env has to be activated before running the command
My configuration is Windows 10 and Python 3.9. These are the commands:
.\env\Scripts\activate
pdoc ./file.py -o ./docs
This is the .pre-commit-config.yaml I tried:
repos:
- repo: https://github.com/pre-commit/pre-commit-hooks
rev: v4.4.0
hooks:
- id: check-yaml
- repo: local
hooks:
- id: env
name: Activate env
language: system
entry: .\env\Scripts\activate
- repo: local
hooks:
- id: pdoc
name: Run pdoc
language: system
entry: pdoc ./file.py -o ./docs
# Output:
check yaml...............................................................Passed
Activate env.............................................................Failed
- hook id: env
- exit code: 1
Executable `.envScriptsactivate` not found
Run pdoc.................................................................Failed
- hook id: pdoc
- exit code: 1
Executable `pdoc` not found
This may not be intuitive use of pre-commit, but I need a way to run the pdoc commands before every commit. This is intended for use inside the same organization, so the set up will be the same on every device.
Edit 1: I tried one of the suggestions from anthony sottile, but there are still some errors because of unexpected arguments.
repos:
- repo: https://github.com/pre-commit/pre-commit-hooks
rev: v4.4.0
hooks:
- id: check-yaml
- repo: local
hooks:
- id: env
name: Activate env
language: system
entry: ./env/Scripts/pdoc.exe file.py -o ./packages
# Output:
check yaml...............................................................Passed
Activate env.............................................................Failed
- hook id: env
- exit code: 2
usage: pdoc.exe [-o DIR] [-d {markdown,google,numpy,restructuredtext}]
[-e module=url] [--favicon URL] [--footer-text TEXT]
[--logo URL] [--logo-link URL] [--math | --no-math]
[--search | --no-search] [--show-source | --no-show-source]
[-t DIR] [-h HOST] [-p PORT] [-n] [--help] [--version]
[module ...]
pdoc.exe: error: unrecognized arguments: .idea/misc.xml .idea/inspectionProfiles/profiles_settings.xml .pre-commit-config.yaml file.py
With the suggestions of anthony sottile the following changes to the .pre-commit-config.yaml worked for me:
repos:
- repo: https://github.com/pre-commit/pre-commit-hooks
rev: v4.4.0
hooks:
- id: check-yaml
- repo: local
hooks:
- id: env
name: Activate env
language: system
pass_filenames: false
entry: ./env/Scripts/pdoc.exe ./file.py -o ./packages