docs(store): add API reference

[alvrs]

This approach lets us generate API docs from NatSpec and render them on the docs page.
Limitations:

• No sidebar quickjumps for headlines (nextra limitation with imported markdown)
• Links to github source and links to eg other interfaces in the docs don't work (bc forge is generating invalid links for github, and the nextra sitemap is different from the one expected by forge)

We could work around both limitations by creating a script that parses the raw forge markdown output, processes it (eg to replace links and change headlines from H1 to H2 etc), and render it as plain mdx file in the docs.

Curious about your thoughts on this approach @holic @qbzzt

[changeset-bot]

⚠️ No Changeset found

Latest commit: a82dcf3

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[holic]

We could work around both limitations by creating a script that parses the raw forge markdown output, processes it (eg to replace links and change headlines from H1 to H2 etc), and render it as plain mdx file in the docs.

another approach could be a component that wraps each markdown file and does ~the same (though it prob wouldn't solve sidebar issues)

[holic]

Looks decent, despite shortcomings!

https://mud-next-docs-fv7gsl0r0-latticexyz.vercel.app/store/reference/store-core

Seems like the imported markdown is also missing from search, which is a big downside IMO. Bigger than the ones mentioned above.

[alvrs]

Seems like the imported markdown is also missing from search, which is a big downside IMO. Bigger than the ones mentioned above.

Good catch! I think to solve this we have to print the markdown instead of using the nextra component

[alvrs]

Added a script to post-process the forge doc output and render it as raw mdx in the docs

[qbzzt]

I love it. There is some formatting weirdness (compare http://localhost:3000/store/reference/store-core#getfieldlayout and http://localhost:3000/store/reference/store-core#getvalueschema, for example). Also, I'd expect the italicized test to be the one in the purple box, not what's in the green one.

However, these are minor and we have lots of docs to go through. I saw merge it now and deal with formatting later. It's clear enough.

[alvrs]

Re italic font vs regular font: I think that depends on what has the `@notice` tag (regular) and what has the `@dev` tag (italic) in the NatSpec. We need to do another pass for NatSpec in the IStore interfaces, we had skipped those bc they were not relevant for the audit.

…

On Fri 13. Oct 2023 at 19:56, Ori Pomerantz ***@***.***> wrote: ***@***.**** approved this pull request. I love it. There is some formatting weirdness (compare http://localhost:3000/store/reference/store-core#getfieldlayout and http://localhost:3000/store/reference/store-core#getvalueschema, for example). Also, I'd expect the italicized test to be the one in the purple box, not what's in the green one. [image: Screenshot 2023-10-13 at 12 53 51 PM] <https://user-images.githubusercontent.com/12722969/274993667-e9e48119-934e-4011-9b1e-9fa37adfe8b0.png> However, these are minor and we have lots of docs to go through. I saw merge it now and deal with formatting later. It's clear enough. — Reply to this email directly, view it on GitHub <#1762 (review)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AVI5JBQEZJCQDTIJHMLTAHLX7F6F7AVCNFSM6AAAAAA56C2VKWVHI2DSMVQWIX3LMV43YUDVNRWFEZLROVSXG5CSMV3GSZLXHMYTMNZXGA2TIOBZGA> . You are receiving this because you authored the thread.Message ID: ***@***.***>