new Astro docs roadmap

[Naramsim]

Hi @Indyandie , I'll write here a checklist of required and optional things (that I see as of now) to do in order to move from our current website to the Astro one:

• import all the API v2 sections as they appear now (https://pokeapi.co/docs/v2). Or find a way to have the same info on the OpenAPI section. One thing that the OpenAPI section seems to be lacking is the the types of the objects
• The front-page try-it-now

Optional:

• A translation system
• A section for writing how-to guides

[Indyandie]

Hey @Naramsim, thanks for putting this together.

1. Can you help outline a check list of the things we'll need for API v2 sections to be represent accurately. We might be able to just update the openAPI spec, but if not we could just recreate what's there at the moment.
   • Maybe we could use berries as an example.
     • Berries Section (Current Site)
     • Berries Tag) (New Site)
     • First thing that jumps out is that missing descriptions in the response
2. Try it now should be fairly simple.

Optional

1. Starlight supports i18n. I think this might be bigger project.

• Do we have any translations at the moment?

1. The Step component could come in handy for writing how-tos.

[Naramsim]

Regarding 1. I think many things are missing. For example:

• The reference returned JSON
• The description for each property
• The basic types. i.e.: the flavors for the berries are typed as list BerryFlavorMap and in the Astro one is simply Array<object>. But it's cool that you can click and see how the object is composed. But if you click too many nested properties it might become overwhelming, maybe.

Some things we need to rework

• The API doesn't have any kind of authorization, so listing everytime CookieAuth, BasicAuth, None is useless. It's hardcoded api.example.org.
• In the pokemon section there's references to ability_list and ability_retrieve.
• We should order everything alphabetically
• Remove the bottom buttons to navigate to previous and next resources. Imho are not useful
• We might as well get rid of the right hand side column On this page. So we have more space for actual content. Or maybe show it only on large screens. On my 13" everything is a little crammed.
• The application/json select is also useless. (We could hide as well the 200 status code.)
• I like the continous scrolling of CloudFlare. i.e.: https://developers.cloudflare.com/api/resources/accounts/methods/create/ SO for the berries one could scroll all the way from Overview to Get berries by flavor. As it is in the current website.
• I think CF documentation is a good place to look at for suggestions. And I think they use Astro as well.

[Naramsim]

Hi @Indyandie , I just wanted to check if you saw my message, no stress. If you don't have time to update the code there's no problem!

[Indyandie]

Hi @Naramsim , thanks for checking in. It’s on my radar, and I’m still figuring out the best approach. I’ll follow up once I’ve got a solid plan together.