fix(docutils): add & adjust various log messages #21160
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
There was a problem hiding this comment.
Pull Request Overview
This PR refines logging and error messages for the docutils executable to improve user feedback during validation, initialization, build, and deployment.
- Updates various error and debug messages to be more descriptive and consistent
- Adds new checks such as verifying that MkDocs is installed
- Renames a couple of variables/functions for improved clarity and consistency
Reviewed Changes
Copilot reviewed 7 out of 7 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
| packages/docutils/lib/validate.ts | Refined error/debug messages and adjusted version mismatch handling |
| packages/docutils/lib/scaffold.ts | Renamed internal variable for clarity and streamlined patch logging |
| packages/docutils/lib/init.ts | Improved Python path resolution and error messaging |
| packages/docutils/lib/fs.ts | Replaced safeWriteFile with writeFileString, removing conditional overwrite logic |
| packages/docutils/lib/constants.ts | Removed unused constant for file exists error |
| packages/docutils/lib/builder/site.ts | Enhanced error handling with MkDocs installed check |
| packages/docutils/lib/builder/deploy.ts | Improved error messages and added additional logging for clarity |
Comments suppressed due to low confidence (2)
packages/docutils/lib/fs.ts:159
- The new writeFileString function no longer supports conditional file overwriting. Ensure that all consumers have updated their logic if preventing overwrites was previously relied upon.
export function writeFileString(filepath: string, content: JsonValue) {
packages/docutils/lib/init.ts:142
- [nitpick] Consider renaming 'foundPythonpath' to 'foundPythonPath' to follow consistent camelCase naming conventions.
const foundPythonpath = pythonPath ?? (await findPython());
packages/docutils/lib/init.ts
Outdated
| pythonPath = pythonPath ?? (await findPython()) ?? NAME_PYTHON; | ||
| const foundPythonPath = pythonPath ?? (await findPython()); | ||
| if (!foundPythonPath) { | ||
| throw new DocutilsError(`Could not find Python in PATH. Is it installed?`); |
There was a problem hiding this comment.
I see the same message is repeated. Perhaps, we could move it to a separate function called requirePython ?
There was a problem hiding this comment.
I've extracted the code that raises an error to a separate method, but for the code that returns this.fail I only extracted the message string, since those would still need a return call.
| throw new DocutilsError(`Could not find property 'engines.npm' in ${NAME_PACKAGE_JSON}. This is a bug`); | ||
| } | ||
|
|
||
| const npmPath = this.npmPath ?? (await whichNpm()); |
There was a problem hiding this comment.
not sure if it makes sense in this context, but on Windows npm is a batch executable
There was a problem hiding this comment.
Yes, I was actually struggling quite a bit with this...
teen_process's exec calls spawn, which doesn't work for bat/cmd files on Windows, unless shell: true is set.
Adding this flag then caused it to start failing for all paths that contain a space (node/npm is installed in Program Files by default).
I tried wrapping the path using util.quote, but that additionally escaped the backslashes in the path, causing it to still fail.
For now I've left it as is - hopefully it can be investigated more in the future.
Actually, the exec call for retrieving the tsc version was also failing on Windows, but I have not investigated that one yet.
There was a problem hiding this comment.
try to enable windowsVerbatimArguments option if on windows, similar to https://github.com/appium/appium-adb/blob/ae59cfb7f1c89e2c3f869c54fd3e70cc19b22f03/lib/tools/apk-signing.js#L53
There was a problem hiding this comment.
Unfortunately this doesn't help. In fact, Node automatically sets this option "when shell is specified and is CMD".
There was a problem hiding this comment.
I managed to fix both the npm and tsc checks by using npm.exec from @appium/support. A similar approach is already used in appium/lib/config.js.
Both checks now work as expected on Windows, but I will also validate it on macOS tomorrow.
There was a problem hiding this comment.
Confirmed on macOS that the fix still keeps the expected behavior 👍
mykola-mokhnach
approved these changes
Mar 31, 2025
4bcbc5a to
05272b6
Compare
KazuCocoa
approved these changes
Apr 2, 2025
eglitise
added a commit
that referenced
this pull request
Apr 26, 2025
* chore(tsconfig): update dependency @tsconfig/node14 to v14.1.3 (#21065) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> * chore(workflows): update peter-evans/create-pull-request action to v7.0.8 (#21066) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> * chore(deps): update dependency typescript-eslint to v8.26.0 (#21068) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> * chore(deps): update definitelytyped (#21067) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> * chore(docutils): update dependency typescript to v5.8.2 (#21057) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> * chore(docutils): update dependency mkdocs-git-revision-date-localized-plugin to v1.4.1 (#21071) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> * feat(images-plugin): supports image elements included in actions. (#21055) * chore(types): update dependency type-fest to v4.37.0 (#21073) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> * chore(deps): update dependency finalhandler to v2 (#21074) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> * test: Update tests of images plugin (#21078) * test(images-plugin): Fix test host (#21079) * chore(support): update dependency axios to v1.8.2 (#21080) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> * chore(deps): update dependency eslint-config-prettier to v10.1.1 (#21081) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> * chore(fake-driver): accept 3.0.0-beta.0 as well (#21076) * feat: Add storage plugin (#21075) * chore(deps): update dependency @types/node to v22.13.10 (#21084) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> * docs(base-driver): remove outdated READMEs (#21083) * chore(deps): update eslint-related packages to v9.22.0 (#21085) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> * feat(storage-plugin): Tune the files keeping behaviour (#21086) * docs(appium): fix a broken character that caused incorrect rendering of mkdocs (#21090) (#21091) * chore(storage-plugin): Simplify add to storage logic (#21092) * chore(docutils): update dependency mkdocs-git-revision-date-localized-plugin to v1.4.4 (#21093) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> * docs: add storage-plugin documentation (#21096) * chore: fix typo * chore: list storage-plugin as a known plugin * docs: align storage-plugin docs with other plugins * chore: address comments * chore(deps): update eslint-related packages (#21097) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> * fix(base-driver): Fix proxy url generation (#21099) * chore: publish - appium@2.17.0 - @appium/base-driver@9.16.3 - @appium/base-plugin@2.3.4 - @appium/docutils@1.0.33 - @appium/driver-test-support@0.7.7 - @appium/execute-driver-plugin@4.0.3 - @appium/fake-driver@5.7.2 - @appium/fake-plugin@3.2.4 - @appium/images-plugin@3.1.0 - @appium/plugin-test-support@0.3.52 - @appium/storage-plugin@0.1.0 - @appium/support@6.0.7 - @appium/test-support@3.1.7 - @appium/tsconfig@0.3.5 - @appium/types@0.25.2 - @appium/universal-xml-plugin@1.0.31 * chore(deps): update dependency eslint-import-resolver-typescript to v3.8.5 (#21101) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> * chore(support): update dependency axios to v1.8.3 (#21102) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> * chore(execute-driver-plugin): update dependency webdriverio to v9.12.0 (#21072) * chore(deps): update dependency eslint-import-resolver-typescript to v3.8.6 (#21103) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> * chore(deps): update dependency eslint-import-resolver-typescript to v3.8.7 (#21107) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> * chore(docutils): update dependency mkdocs-material to v9.6.8 (#21108) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> * chore(universal-xml-plugin): update dependency fast-xml-parser to v5 (#21109) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> * chore(deps): update dependency eslint-import-resolver-typescript to v3.9.0 (#21113) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> * chore(docutils): update dependency mkdocs-git-revision-date-localized-plugin to v1.4.5 (#21112) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> * chore(deps): update dependency eslint-import-resolver-typescript to v3.9.1 (#21115) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> * chore(docutils): update dependency mkdocs-material to v9.6.9 (#21121) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> * fix(base-driver): Exclude proxied headers from the server response (#21120) * chore: publish - appium@2.17.1 - @appium/base-driver@9.16.4 - @appium/base-plugin@2.3.5 - @appium/docutils@1.0.34 - @appium/driver-test-support@0.7.8 - @appium/execute-driver-plugin@4.0.4 - @appium/fake-plugin@3.2.5 - @appium/images-plugin@3.1.1 - @appium/storage-plugin@0.1.1 - @appium/support@6.0.8 - @appium/test-support@3.1.8 - @appium/universal-xml-plugin@1.0.32 * docs: update zh contributing documentation (#21117) * Translate Validation of Individual Arguments via AJV section * Complete the translation of the config system file * chore(docutils): update dependency consola to v3.4.2 (#21124) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> * chore(deps): update dependency @types/express to v5.0.1 (#21126) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> * chore(support): update dependency axios to v1.8.4 (#21127) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> * chore(execute-driver-plugin): update dependency webdriverio to v9.12.1 (#21129) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> * chore(deps): update dependency typescript-eslint to v8.27.0 (#21131) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> * chore(eslint-config-appium-ts): update dependency eslint-import-resolver-typescript to v4 (#21119) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> * chore(test-support): update dependency sinon to v19.0.4 (#21130) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> * chore(deps): update dependency @types/node to v22.13.11 (#21135) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> * feat: Add a possibility to mask sensitive log values depending on request headers (#21123) * chore(deps): update eslint-related packages to v9.23.0 (#21138) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> * chore(types): update dependency type-fest to v4.38.0 (#21140) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> * chore(deps): update definitelytyped (#21139) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> * chore(test-support): update dependency sinon to v19.0.5 (#21141) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> * chore(deps): update eslint-related packages (#21142) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> * chore(test-support): update dependency sinon to v20 (#21143) * chore(test-support): update dependency sinon to v20 * remove usingPromise --------- Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> Co-authored-by: Mykola Mokhnach <mokhnach@gmail.com> * chore(deps): update dependency eslint-import-resolver-typescript to v4.2.5 (#21146) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> * chore(deps): update definitelytyped (#21147) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> * chore(storage-plugin): Use base driver import for W3C error response creation (#21153) * chore(deps): update dependency eslint-import-resolver-typescript to v4.2.7 (#21155) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> * chore(execute-driver-plugin): update dependency webdriverio to v9.12.2 (#21151) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> * chore(docutils): update dependency yaml to v2.7.1 (#21158) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> * chore(deps): update dependency eslint-import-resolver-typescript to v4.3.1 (#21159) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> * feat(base-driver): Accept `x-request-id` as override to generated requestId in `handleLogContext` (#21154) * chore(docutils): update dependency mkdocs-material to v9.6.10 (#21161) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> * chore(deps): update dependency typescript-eslint to v8.29.0 (#21165) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> * chore(deps): update definitelytyped (#21164) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> * chore(docutils): update dependency mkdocs-material to v9.6.11 (#21167) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> * chore(types): update dependency type-fest to v4.39.0 (#21168) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> * fix(docutils): add & adjust various log messages (#21160) * fix(docutils): add & adjust various log messages * fix: use npm from support package for npm calls * chore(deps): update dependency @types/node to v22.14.0 (#21172) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> * chore(types): update dependency type-fest to v4.39.1 (#21173) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> * fix(logger): Error stack logging (#21176) * chore(execute-driver-plugin): update dependency webdriverio to v9.12.3 (#21177) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> * chore(universal-xml-plugin): update dependency fast-xml-parser to v5.2.0 (#21178) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> * chore(docutils): update dependency typescript to v5.8.3 (#21179) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> * chore(execute-driver-plugin): update dependency webdriverio to v9.12.4 (#21180) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> * chore(deps): update eslint-related packages to v9.24.0 (#21182) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> * chore(support): update dependency sharp to v0.34.0 (#21183) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> * feat(docutils): add MkDocs Material codeblock & text format features (#21184) * chore(docutils): reorder Markdown extensions alphabetically * feat(docutils): add MkDocs Material codeblock features * chore(docutils): explicitly add Markdown tables support * feat(docutils): add MkDocs Material linked tabs * feat(docutils): add MkDocs Material text format features * feat(docutils): add MkDocs Material task list * fix(ci): run on all Node LTS versions instead of only active (#21185) * fix(ci): run on LTS versions instead of only active * chore: address comments * chore(deps): update dependency eslint-import-resolver-typescript to v4.3.2 (#21186) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> * chore(deps): update dependency typescript-eslint to v8.29.1 (#21189) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> * chore(support): update dependency sharp to v0.34.1 (#21191) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> * chore(deps): update dependency tsd to v0.32.0 (#21194) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> * chore(deps): update dependency eslint-config-prettier to v10.1.2 (#21195) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> * chore(deps): update dependency lerna to v8.2.2 (#21197) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> * chore(deps): update dependency @types/node to v22.14.1 (#21199) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> * chore(execute-driver-plugin): update dependency webdriverio to v9.12.5 (#21200) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> * chore(base-driver): Mark IME commands and receive_async_response as deprecated (#21201) * docs(appium): add NovaWindows driver to Appium other drivers list (#21202) * chore(deps): update dependency typescript-eslint to v8.30.1 (#21206) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> * chore(types): update dependency type-fest to v4.40.0 (#21208) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> * chore(base-driver): Mark /session/:sessionId/network_connection deprecated (#21209) * chore(execute-driver-plugin): update dependency webdriverio to v9.12.6 (#21210) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> * chore(docutils): update dependency mkdocs-material to v9.6.12 (#21211) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> * chore(deps): update eslint-related packages (#21214) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> * chore(deps): update eslint-related packages (#21216) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> * chore(execute-driver-plugin): update dependency webdriverio to v9.12.7 (#21218) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> * docs: update Appium 2 migration guide (#21215) * docs: rewrite Appium 2 migration guide * docs: reorder breaking changes * docs: identify changed endpoints * docs: improve code example * docs: address comments * chore(universal-xml-plugin): update dependency fast-xml-parser to v5.2.1 (#21220) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> * docs: remove SeleniumConf banner (#21221) * docs(appium): address default timeout in newCommandTimeout (#21222) * chore: publish - appium@2.18.0 - @appium/base-driver@9.17.0 - @appium/base-plugin@2.3.6 - @appium/docutils@1.1.0 - @appium/driver-test-support@0.7.9 - @appium/eslint-config-appium-ts@1.0.4 - @appium/execute-driver-plugin@4.0.5 - @appium/fake-plugin@3.2.6 - @appium/images-plugin@3.1.2 - @appium/logger@1.7.0 - @appium/opencv@3.0.9 - @appium/plugin-test-support@0.3.53 - @appium/storage-plugin@0.1.2 - @appium/support@6.1.0 - @appium/test-support@3.1.9 - @appium/types@0.25.3 - @appium/universal-xml-plugin@1.0.33 * chore(deps): update dependency @types/node to v22.15.2 (#21223) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> * chore(support): update dependency axios to v1.9.0 (#21225) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> --------- Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> Co-authored-by: kkb912002 <57607392+kkb912002@users.noreply.github.com> Co-authored-by: Mykola Mokhnach <mokhnach@gmail.com> Co-authored-by: Kazuaki Matsuo <fly.49.89.over@gmail.com> Co-authored-by: Sakura Nene <blade1565@outlook.com> Co-authored-by: Jonathan Lipps <jonathan.lipps@sony.com> Co-authored-by: zhangxh075 <zhangxh075@163.com> Co-authored-by: Regan Karlewicz <regan@karlewr.net> Co-authored-by: Teodor Nikolov <teo8447@gmail.com>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This PR adjusts validation for the
docutilsexecutable:appium-docs initis called without Python being installedappium-docs buildis called withoutmkdocsbeing installedappium-docs validateappium-docs build --deploy --serveappium-docs initwith an existingtsconfig.jsonfileappium-docs validate