Add API docs to e2e-test-utils package

[oandregal]

Testbed for #13329

The API section within the README of this package has been generated automatically with a new package that's in the works.

[gziolo]

This is amazing 🔮 I wil take a closer look tomorrow ☀️

[gziolo]

I left my thoughts. I don't see any blockers, mostly ideas on how to iterate further and make maintenance easier. Let me know what do you think and whether you plan to apply any changes to this PR.

[gziolo]

Just noting that this logo is usual at the end of the file.

This made me think that maybe we simplify this process a bit and we only reference API file in the file and generate the document inside docs/api.md file or something like that. The idea would be that we only have to update one file which can be completely erased every time it gets updated. Another way of handling it is to come up with some start and end token which you put inside readme file and they get overriden with the docs script.

[oandregal]

https://github.com/WordPress/gutenberg/pull/13329/files#r256816506 is another case where using tokens instead of using section titles would be beneficial.

[gziolo]

This is cool, however, in the iteration 2 I would love to see it traversing to the actual source code ✨

[oandregal]

I thought about that as well. We already look up the symbol declaration in many cases to retrieve the JSDoc; not in all cases, though. It'd be a nice addition, and I wonder if perhaps we should add both (export statement + symbol declaration). Undecided what would be best, but it's doable.

[gziolo]

Noting that this output is a bit different than we see for data stores in the existing docs, see:

https://github.com/WordPress/gutenberg/blob/master/docs/designers-developers/developers/data/data-core-editor.md

At some point, we should consolidate for consistency.

[oandregal]

Let me know what do you think and whether you plan to apply any changes to this PR.

This PR has taught me two things:

• we should improve the Markdown injection mechanism (perhaps using tokens instead of section titles).
• we should have a command available to regenerate the API docs easily.

Learning about how to improve the tool was the original goal of this PR, so I guess we could merge it, backport these lesson to the tool and use another package as the next testbed. What do you think @gziolo ?

[gziolo]

Yes, this looks great. I wasn't sure if you want to merge it as is or iterate further. Thanks for working on this PR. It should be super helpful for those who want to write e2e tests 👍

BTW, I moved the WP logo to the bottom of the file for consistency and to make it less exposed :)

[oandregal]

BTW, I moved the WP logo to the bottom of the file for consistency and to make it less exposed :)

Oh, I missed that, thanks for taking care of it!