search

unicode-org / icu4x

Solving i18n for client-side and resource-constrained environments.
https://icu4x.unicode.org
Other
1.37k stars 176 forks source link

Move tutorials and docs to mdbook #2929

Open Manishearth opened 1 year ago

Manishearth commented 1 year ago

We have a ton of docs and tutorials (yay), it would be nice if we could present them in a more organized fashion.

I suggest we structure this as an mdbook. We can structure this as named pages sorted into chapters (with subchapters/subpages if necessary!). It also gets us doctests for free.

I'm envisioning an intro section that gets people oriented and tells them where to go next in the book, and we can start filling out chapters. A thing I really like about mdbook is that you can define WIP chapters where there will be a placeholder shown in the book, so you can organize your book without having all of the chapters written.

Manishearth commented 1 year ago

Another thing mdbook gets us is that complicated things like LruDataCache (https://github.com/unicode-org/icu4x/pull/2914) can be put in a subpage so they don't clutter the main tutorial but are still noticeable

sffc commented 1 year ago

Can we keep the mdbook in the same repo, or do we need to make another repo for it?

Manishearth commented 1 year ago

It can be in the same repo. We can also add a publish step to GHA and send it somewhere.