This changes how packages get their titles (the h1 in the commands page, which is used by mkdocs in the nav bar).
A new option, `packageTitles` is available in `typedoc.json`. This is an array of objects like so:
```json
{
"packageTitles": [
{"name": "@appium/fake-driver": "title": "Fake Driver"},
{"name": "@appium/fake-plugin": "title": "Fake Plugin"}
]
}
```
This allows granular control over how each package is titled. However, if this option is not provided, the plugin will "extract" a title from the `package.json` of each package, assuming that package is an Appium extension. By default, it will name drivers `Driver: ${appium.driverName}` and plugins `Plugin: ${appium.pluginName}` where `appium` is a prop in `package.json`.
If the package is _not_ an extension but _does_ have commands -- and currently the only package that fulfills this criteria is `@appium/base-driver` -- _and_ is in a multi-package project, the title will be `${name} Commands` where `name` is from `package.json`. Otherwise, if we are documenting a project with a single package (e.g., a 3p extension) _and_ we cannot otherwise derive a title, we will just use `Commands` for the title.
While we _could_ update `appium-docs` to support multiple languages, it's easier to just reuse what we have.
This changes the `build-docs` script in `appium/docs/scripts` to use new APIs `deploy()`, `buildReferenceDocs()` and `deploy()` from `@appium/docutils`.
The "default" language is `en`, and `packages/appium/docs/reference/en` is where TypeDoc outputs its markdown files. This is configured in the `typedoc.json`. Once TypeDoc has run, each language's `mkdocs.yml` is updated with the new `nav` as computed from the output of TypeDocs. Importantly--and I don't know if this is right--those TypeDoc-docs are _not_ copied into the specific language dir (if not `en`) and instead are referenced within `en`. This _may_ pose a navigation problem as it's _might_ be possible for a browsing user to accidentally switch away from the target language.
The script `copy-assets` remains the same and script `build-reference` was removed due to duplication.
- Do not send boolean flags to `mike`
- Do not send `mike serve`-specific args to `mike deploy`
- Derive version from `package.json` if no version present (like the CLI docs say it should)
- `version` and `alias` are positional args to `mike deploy`/`mike serve`, not options
- Fix update nav logic
- Fix monkeypatching of TypeDoc if `typedoc` is not installed in the `node_modules` of a workspace
- Fix parsing of `typedoc.json`
- Fix finding of `typedoc.json`
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
When validating `mkdocs.yml`, `appium-docs` is now aware of the `INHERITS` property, and expands this property (by loading more `mkdocs.yml` files).
Also:
- Updated the types for `mkdocs.yml`
- Squelch warnings from `YAML.parse()`
- Change YAML indentation back to 2, since that seems to be correct and I was confused
- 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)
Christopher Hiller