- Better grouping of `validate` command options in `--help`
- Move some more constants into the module
- Removed the "guess" functions and replaced them with functions which use `which` to actually find the necessary executables
- Moved `isStringArray()` to `util`
- Fixed some error messages and added more
- Simplified use of `DocutilsValidator#fail()`
- Removed option for custom path to `requirements.txt`
It now shows "Command API" if there's only one 3p extension we're documenting, and "(name) Command API" if there are multiple (e.g. in the case of a monorepo)
This value defaults to `false`, as extension authors will typically not want that stuff.
As with removal of non-command reflections (via the plugin's `outputModules` option), this happens in a post-processing step after conversion but before rendering.
This modifies the validator to collect all of the errors from validation (except those that are "unexpected" though not _so_ unexpected that I did not account for them; stuff like "unparseable output from `pip list --json`") and display them as they happen without aborting the entire validation process.
`build` now executes both `typedoc` and `mkdocs` unless options to one run or the other are passed.
- renamed `init-task` to `scaffold`
- renamed `build` to `typedoc`
- fix JSON5 stringification
- use typedoc's facilities for reading its own config files, which absolves us from having to expand the `extends` prop in `typedoc.json` (if any)
The `validate` command checks the status of the environment and reports any problems to the user.
This includes Python env and dep checks, typescript and typedoc checks of installed version and configuration files (to varying degrees).
Also:
- Convert `mkdocs.js` to TS; remove `assertMkDocs` as that moved into the `validate` module
- JSON5 support for `tsconfig.json` (this is important, because the default `tsconfig.json` is a JSON5 file)
- Sorted the options in the `cli` module
- Renamed `types` to `model`
- Moved some constants into new module `constants`
This provides some tools for extension authors to easily setup and configure their packages to build docs and create documentation via TypeDoc & mkdocs.
apparently the "files" prop does not take into account what the ".npmignore" file says, so these were still getting published.
hopefully this will fix it.
The "old" way of defining tuples is `[T, U]`, but I think TS 4.7 introduced "named" tuples, which at least provides a little bit of context to consumers, e.g., `[foo: T, bar: U]`. Since a tuple is just a fixed-length array, the names aren't actually used in code, but are surfaced in type information and error messages regardless.
Also:
- Fixed bad param name in definition of `SessionHandler`
- Used a semantically-correct type for `StopScreenRecordOptions.formFields`
Contains significant changes to comment derivation.
Given a command method in an external driver, these changes cause the plugin to search a) the method itself, b) the method's signature (which may come from `BaseDriver` or even `DriverCore`), the method map, and the `ExternalDriver` interface for comments (in that order). It picks the first "summary" / "description" found, but otherwise it will _merge_ any and all block tags found, given the same precedence. So if, for example, a `@see` tag exists in cmd method `ExternalDriver.foo()` but not in `MyDriver.foo()`, the plugin will find that `@see` tag and put it into the data to be rendered by the theme for the command associated with `MyDriver.foo()`.
This also works with `@example`, with a change: the examples side-step the usual rendering (by `typedoc-plugin-markdown`'s theme; this is due to tight coupling and complexing necessary in overriding the default behavior by simply adding an overriding template or partial), and are rendered per-language (since it's likely/expected that each method will have examples in several languages). The language of the example is detected via the _fenced code block_ as used in the example. In markdown, we're currently using some headers to split examples up, but we also render a token as an HTML comment which can be used on the `mkdocs` side of things to detect the example and perform further post-processing (e.g. as a set of tabs).
If a command has examples, the examples will be surrounded by (in addition to headers for each language) this token pair:
```html
<!-- BEGIN:EXAMPLES -->
...
<!-- END:EXAMPLES -->
```
Each language's fenced code block is surrounded by the following token pair _within_ the above pair:
```html
<!-- BEGIN:EXAMPLE lang=$lang -->
...
<!-- END:EXAMPLE -->
```
...where `$lang` is the _proper name_ for a language, e.g., `JavaScript` or `Ruby`. The fenced code blocks themselves remain unchanged and will contain the "identifier" for the language, e.g., `js` or `javascript` or `rb` or `ruby` (i.e. they are _not_ normalized).
Also:
- changed the type of `KnownMethods` to be a `Map<string, CommandMethodDeclarationReflection>`, as the value of the `comment` prop is better derived via `deriveComments()`. This changes `findAsyncMethodsInReflection()` as well
- memoized `AppiumPluginLogger.createChildLogger()` to avoid creating identical loggers
- renamed `ProjectCommands.empty` => `ProjectCommands.isEmpty`
- `CommandReflection`'s `constructor` now expects a `log` parameter
- Hopefully easier-to-understand verbose logging
renovate[bot]