* fix(docutils): set mike version to major.minor by default
* Update packages/docutils/lib/builder/deploy.ts
Co-authored-by: Christopher Hiller <boneskull@boneskull.com>
---------
Co-authored-by: Christopher Hiller <boneskull@boneskull.com>
* 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.
* docs(appium): fix error in docs build script
in the case where the gh-pages branch was out of sync with local
it would just fail. now we will attempt to rebase first.
* docs(appium): fix error in docs build argify
* test(typedoc-plugin-appium): fix failing test fixture
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.
This change ensures when running `mkdocs` or `mike` with the `--serve` flag, the output is unbuffered and stdio is inherited from the parent process.
This will show helpful things like _the URL at which the development server is running_.
`type-fest`@3.6.0 has a `TsConfigJson` type which no longer contains `unknown` (courtesy of yours truly), so we can use it directly instead of wrapping it in `Jsonify`.
- 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.
- 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`
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)
Kazuaki Matsuo