docs: move from jekyll pages to a better doc engine

FuelLabs / fuels-ts

Fuel Network Typescript SDK

https://docs.fuel.network/docs/fuels-ts/

Apache License 2.0

44.04k stars 1.35k forks source link

docs: move from jekyll pages to a better doc engine #457

Closed luizstacio closed 1 year ago

luizstacio commented 2 years ago

Items;

[ ] change typedoc to generate to the new temple engine
[ ] change the deploy config on gh-pages
[ ] make a reusable block for ### Full SDK Installation and reuse them inside packages README file

Notes;

One good template is the nextra.

arboleya commented 1 year ago

Nextra seems to be an excellent solution, but I have never used it.

I've seen a couple of projects using it, and also on our other repos:

Congrats on these! @FuelLabs/frontend 🤘 🚀

@FuelLabs/frontend Do you have any pros and cons you'd like to point out about the tool?

@FuelLabs/sdk-ts Anyone else with experience using Nextra?

pedronauck commented 1 year ago

I guess we could improve the next project we have inside the wallet and try to use it as a base for all projects. Could be a template, a boilerplate, a generator, or even a tool. But it will be essential in order to have standard docs across the entire organization.

arboleya commented 1 year ago

@pedronauck Excellent point.

I like the sound of it, but I wonder how complicated that would be.

arboleya commented 1 year ago

Another candidate could be Vite Press:

https://vitepress.vuejs.org

It has many goodies for Markdown, import code snippets being one of them:

https://vitepress.vuejs.org/guide/markdown#import-code-snippets

Dhaiwat10 commented 1 year ago

I have used Nextra multiple times in the past, but never with anything along the lines of auto-generated docs.

arboleya commented 1 year ago

Yes, in this case, we wouldn't be auto-generating docs from JavaDoc style annotations via TypeDoc anymore, but writing everything by hand and using code snippets where applicable to denote methods usage and whatnot.

I would be OK with throwing TypeDoc away and stopping using those styles of API documentation, which, IMO, are not very useful. These generated docs are often vague and mechanical and do not seem to provide advantages beyond what one could get by reading the source code directly.

@Dhaiwat10 What are your thoughts about Nextra? Did you have a good experience using it? Any experience comparing it with other tools such as VitePress or similar?

Torres-ssf commented 1 year ago

@luizstacio mentioned docusaurus as a good candidate for this