feat(aft): Docs commands

[dnys1]

Adds aft docs build and aft docs serve to compile docs and serve docs on a local HTTP server with auto-rebuild, respectively.

[HuiSF]

Is this needed for publishing the built docs with workflow at some point?

[dnys1]

Yeah. Even though amplify_core is Dart-only, the examples we showcase in its docs all reference Flutter packages. So the doc package in amplify_core needs a dependency on Flutter so that we can have Flutter-specific samples in the amplify_core docs.

[fjnoyp]

Would the next step be to automatically call your aft build docs command to generate docs for each release?

Is it possible for users navigating our Github to see the index.html of that package's doc output in the current package folder? So if they're navigating our code and want to see docs for datastore or aft, they can directly see the docs/index.html and get the information they need directly within AmplifyFlutter/packages/datastore?

It seems right now we consolidate all docs in the output dir.

[fjnoyp]

I appear to be running the command wrong?

I was able to run aft docs build in aft and get a doc file generated, but when I tried running aft docs build at the packages or root level, I get the following output:

➜  packages git:(feat/aft/docs) ✗ aft docs build
Building docs for amplified_todo...
Building docs for infra...
Building docs for aft...
Building docs for amplify_flutter...

Which then hangs indefinitely. Looking at the code I'm not 100% sure why amplified_todo keeps getting selected as well. Regardless it seems I cannot run the build command for all of amplify? I've run aft clean and bootstrap. I see that the docs files are generated for aft/amplified_todo/infra.

[dnys1]

@fjnoyp

Would the next step be to automatically call your aft build docs command to generate docs for each release?

You mean to verify before publishing?

Maybe. I think a next step could be to build docs for PRs and publish them to a temporary domain similar to the docs repo so that changes are more visible.

Is it possible for users navigating our Github to see the index.html of that package's doc output in the current package folder? So if they're navigating our code and want to see docs for datastore or aft, they can directly see the docs/index.html and get the information they need directly within AmplifyFlutter/packages/datastore?

What would be the benefit of this over visiting the published docs on pub.dev?

I appear to be running the command wrong?

You are running the command correctly. I've pushed some updates to make the error output more clear.

Running aft docs build will run it for every package in the repo, though, which may take a while. I think the goal of these commands is to enable quick docs development, so running aft docs serve from a package directory will serve up that doc's packages and listen for changes which will auto-rebuild the docs.

aft docs build should probably only be used locally with an --include option which targets a specific subset of packages, unless you genuinely wish to see all the packages' docs.

[Equartey]

Do these not exclude the same dir?

[dnys1]

No one is the top-level doc dir, the other applies to all sub-packages

[Equartey]

Can you verify we don't lose any pub points from analysis by changing this? Looks like we're currently 130/140, but lets avoid a regression if possible.

[dnys1]

The goal is ultimately to not require any excludes which will help us catch analysis errors in CI which may show up in pub. Removing this exclude will help make sure our pub points remain high 👍

[fjnoyp]

Thanks for the clarification there, I scoped the docs serve command to get a reasonable subset to run docs against. Looking good so approved.