4.x migration guide

[birkskyum]

just some notes for the migration guide. I tried updating to the next version, just to check it out, but failed to do it.

First i got this error about allReflectionsHaveOwnDocument:

[error] Tried to set an option (allReflectionsHaveOwnDocument) that was not declared. You may have meant:
        cname
        excludeNotDocumented
        theme
        name
        readme
        requiredToBeDocumented
        options
        out

which i fixed by removing the allReflectionsHaveOwnDocument option from typedoc.json.

Then I got this error about a README.md file:

> typedoc && npm run tsnode build/generate-docs.ts

[info] Loaded plugin typedoc-plugin-missing-exports
[info] Loaded plugin typedoc-plugin-markdown
[info] Documentation generated at ./docs/API

> maplibre-gl@4.0.0-pre.1 tsnode
> node --experimental-loader=ts-node/esm --no-warnings build/generate-docs.ts

Error: ENOENT: no such file or directory, lstat 'docs/API/README.md'
    at Object.lstatSync (node:fs:1668:3)
    at __node_internal_ (node:internal/fs/utils:825:8)
    at Object.rmSync (node:fs:1275:13)

[tgreyuk]

Thanks. A migration guide is on list. To fix above error you'ill need to set:

entryFileName: 'README.md`

[birkskyum]

Thanks, it helped. I now see

[info] Documentation generated at ./docs/API

> maplibre-gl@4.0.0-pre.1 tsnode
> node --experimental-loader=ts-node/esm --no-warnings build/generate-docs.ts

node:fs:1666
  handleErrorFromBinding(ctx);
  ^

Error: ENOENT: no such file or directory, lstat 'docs/API/modules.md'
    at Object.lstatSync (node:fs:1666:3)
    at __node_internal_ (node:internal/fs/utils:828:8)
    at Object.rmSync (node:fs:1268:13)

[tgreyuk]

If modules.md does not exist, it will now either be called exports.md or packages.md (depending on the docs output). So just update this line in you generate-docs.ts task:

fs.rmSync(path.join(typedocConfig.out, 'modules.md'));

[tgreyuk]

https://www.typedoc-plugin-markdown.org/docs/v4-release#migrating-from-v3