Split basic API documentation from advanced documentation. about motion-canvas HOT 5 CLOSED

We should also check if the @category tag would be suitable here.
I like the idea of marking things as advanced. I feel like marking entire modules should be enough since they're usually either "basic" (flow, animations, transitions, etc.) or "advanced" (scenes, decorators, etc.).

I've been working on a custom plugin for docusaurus and typedoc because what we use currently is a bit limiting.
So adding a grouping like this shouldn't be a problem.

from motion-canvas.

I've been working on a custom plugin for docusaurus and typedoc

Sick. They really needed that. In particular, it would be nice if the docs were closer to how lodash does it. You might consider trying to open source that as soon as it's stable enough to accept outside pulls.

from motion-canvas.

I'm starting to think we should find a way to get everything basic to be exported from the top level.

import {
  waitUntil,
  waitFor,
  makeKonvaScene,
} from '@motion-canvas/core'

Exporting from the folders forces people to remember not just the names of the functions but also which module they happened to be in, which can feel kinda arbitrary at times. While writing some guides, I started to notice how much more effort it is to explain where things are rather than just saying "add an import for waitUntil" and trusting that they know how.

Not to mention most popular libraries tend to have top-level exports, as far as I remember.

This could also be achieved by simply reexporting things from another module. So it could be @motion-canvas/core/tools or something.

from motion-canvas.

I rarely see top-level imports in libraries nowadays. When a package is distributed using ES modules it usually doesn't have them (See Preact or Konva for instance).
I checked the imports you used as an example and both VS Code and WebStorm had no issues auto-importing them.
So I don't think you need to explicitly state where to import stuff from. You could include imports in the snippets but other than that I don't think it's necessary.

The number of modules we have will also shrink when we extract Konva to a separate package.
We'll essentially be left with: flow, transitions, tweening, types, utils as far as basic modules go.

from motion-canvas.

The separation between basic and advanced documentation is now done manually.
The <ApiSnippet/> component allows nesting individual method/property documentation on any markdown page.
This way, guides can list all the basic, relevant docs directly inside them, see Layouts, Positioning, and Animation flow as examples of this.

from motion-canvas.