anything newer than v4.7.4 fails to ignore an optional arg in `@param {T} [foo]` if `foo` has a default assignment in the function signature. removing the square brackets fixes the issue.
whether or not this is a bug, I am not entirely sure: it is marked as a bug, but it is also not something the TS team is in a hurry to fix, so whatevs.
- in type `DeployOpts`, `mkDocsYml` should have been `mkdocsYml`
- arguments were only being omitted from being passed to `mike` if they were `false`, but it needed to also consider `undefined` values and empty string values. `0` is falsy, but we should not disallow this. thus... "most" falsy values get ignored.
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.
Christopher Hiller