BREAKING CHANGE: @appium/docutils is now an ESM-only package. It can no longer be loaded via CommonJS require(); consumers must use import or dynamic import(). Deep imports into the package's internals are no longer possible — only the public entry point is exposed via exports.
* chore: update prefix flag to deploy-prefix
* chore: fix skipped change for deploy-prefix flag
* chore(deps): bump mike to 2.0.0
* fix: add appium-docs support for --alias-type
* chore: remove deprecated Mike class
* chore: remove export for removed Mike class
* fix: remove rebasing support for appium-docs
* fix(test): add back incorrectly removed argument
* fix(docutils): fixes some weirdness with default behavior and the "implies" keyword
- also squashes an errrant warning
- fix some diff logic when writing to `mkdocs.yml`
* fix(docutils): more robust mike-finding
This makes `appium-docs init` add a needed prop (`typedoc.entryPoint`) to `package.json` of an extension. It will write to `package.json` _by default_, even if it exists--which is different than the default behavior of other scaffolding tasks.
Note that `appium-docs init` will now _fail_ if `--entry-point <some-file>` (or `-e`) is not provided; there's no way for us to guess what it is (this is the _source_ entry point; not necessarily the `main` file). I guess that's technically breaking, but `appium-docs init` should not be part of anyone's workflow.
The resulting solution keeps a bunch of weak refs to `Consola` objects and sets the log level on all of them if it ever changes.
This is--at minimum--easier to understand than the broken `Proxy` implementation.
After we build the reference docs, we need to update the `nav` prop of the given `mkdocs.yml` before building the site. This was only _sorta_ working before; it did not take into account the myriad ways in which the data structure could be expressed (particularly, it did not understand "custom names").
I think I've done this in such a way that if a custom name is provided (they must be provided manually by hand-editing `mkdocs.yml`), it retains them _unless_ the file in question disappears. Or that's the idea. Can't really be too sure; needs tests.
This change makes an attempt to parse the `nav` prop into something "normalized", then the data is processed and recomplexified before writing out to `mkdocs.yml`. However, I've disabled the ability to define a custom header for command docs and/or omit the header entirely, as the latter especially was causing extra complexity and it's already bad enough. I think we can re-enable "custom header" somehow, if needed.
Also added an `--all` flag which causes the nav to be updated with _all_ the TypeDoc-generated content--not just command docs.
This is enabled via `appium-docs build --deploy`. Instead of invoking `mkdocs` directly, `mike` will be invoked.
Implementation is in `lib/builder/deploy.ts`. It's very similar to the MkDocs implementation in `lib/builder/site.ts`; just with new/different options.
I marked the `Mike` class as deprecated, since the new one is fancy
Also rename a few things. `typedoc` module is now `reference` and `mkdocs` module is now `site`.
Moved a couple things into `util` as well
The `nav` module will be in stacked PR
- 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`
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.
Mykola Mokhnach