Migrate to Docusuarus

[lightclient]

The metamask team has put together a really cool docusaurus plugin to display openrpc specs. An example they have deployed is https://docs.metamask.io/wallet/reference/eth_feehistory/

I think this type of doc site feels much more familiar to devs and it accentuates the method and parameter descriptions.

[anukul]

working on this 🫡

[anukul]

@lightclient I have a simple docusaurus version in this state:

The metamask plugin renders links to each method's page in the sidebar, so there's no one specific link to go from the button on the homepage ("API Reference Documentation").

If we want the button to go to a static page, then the PR is straightforward.

But if we want it to go to say an "API Methods" page, that lists all the methods (with links to each method's page), then we need another plugin that composes metamask's plugin to read the spec and render this page (or perhaps a PR to metamask plugin with an option to add the page natively)

What would be the preferred UX here?

[eenagy]

@anukul, there is a linked issue, so each method should be on a separate page. What do you mean by the difference between the two approaches? Maybe it's only me who is confused. A PR or link to the repo for the current approach would be easier to understand if you already have the working code.

[anukul]

there is a linked issue, so each method should be on a separate page.

This is beside the point. Links can point to different sections of the same page. But this discussion is not relevant because the metamask plugin already renders one page for each method in the spec.

What do you mean by the difference between the two approaches? Maybe it's only me who is confused.

Let me try to rephrase the question.

The current spec website has two pages:
1 links to 2

1. Homepage - https://ethereum.github.io/execution-apis/
2. API Reference - https://ethereum.github.io/execution-apis/api-documentation/

For the docusaurus website, we have 1 + N pages by default:
(the metamask plugin renders 1 page for each of the N methods in the spec)

1. Homepage - https://anukul.js.org/execution-apis/
2. eth_accounts - https://anukul.js.org/execution-apis/docs/reference/eth_accounts
3. eth_blockNumber - https://anukul.js.org/execution-apis/docs/reference/eth_blocknumber
   ...

These N links are shown in the sidebar on a different page. But where does the user go from the homepage?

The metamask plugin renders links to each method's page in the sidebar, so there's no one specific link to go from the button on the homepage ("API Reference Documentation").

The question is between a static page (worth discussing what content), or a page that lists all methods, possibly with description, and a link to each method's page.

[lightclient]

Wow @anukul this is looking amazing! As to the preferred ux - here is what I would like to see:

• I'd love for the homepage to go away and we start directly in the spec - preferable with a single page that gives a high level overview of the JSON-RPC and the different namespaces. I'm happy to produce this copy.
• Separate collapsible categories in the sidebar for each API namespace: debug, engine, and eth with the corresponding methods listed. It would be nice for each namespace to have a landing page where a description of the namespace can be provided.
• If possible, would like to hide the example executor on the right for now until we have developed actual examples.

Let me know if this makes sense. Thanks!

[Redidacove]

I have created a docusaurus version of spec
since anukul left it . I am pursuing this open to feedback

[jflo]

this also looks good @Redidacove , do you have a branch somewhere we can look at?