feat(documentation): migrate documentation to Starlight #1742

huijing · 2023-08-17T12:55:41Z

Changes proposed in this pull request

This is a mega-PR that migrates the entire documentation package from Docusaurus to Starlight
There are a number of things that I would like to discuss with the team before this PR can be finalised
1. What to do about the APIs section?
2. Better table design, will probably introduce a Table component or something
3. Discussed before but found Mermaid code in the docs, so asking again, I thought we agreed to generate the diagrams and import?

Context

As part of the docs site consolidation project (see https://www.notion.so/Docusaurus-alternative-RnD-ec117420956f4e5781347631dfdc5c13?pvs=4), we will be migrating the site to Starlight, an Astro-based docs framework.

Checklist

netlify · 2023-08-17T12:55:52Z

✅ Deploy Preview for brilliant-pasca-3e80ec canceled.

Name	Link
🔨 Latest commit	`91e5b68`
🔍 Latest deploy log	https://app.netlify.com/sites/brilliant-pasca-3e80ec/deploys/64e611e18da06a00082d62d9

packages/documentation/src/components/docs/LargeImg/LargeImg.jsx

mkurapov

Looks great, a few things I'd like to have before we merge in

mkurapov · 2023-08-17T13:47:43Z

packages/documentation/package.json

+    "build": "astro build",
+    "preview": "astro preview",
+    "astro": "astro",
+    "graphqlBackend": "./node_modules/.bin/graphql-markdown ../backend/src/graphql/schema.graphql > src/schema-dumps/backend_raw_schema.md",


let's keep the commands as such:
docs:graphql:generate
docs:graphql:generate:backend
docs:graphql:generate:auth

Just for consistency with the other times we generate things

Also, I noticed that some of the generated graphql pages' links don't end up working for me

Could we also have the pnpm build command fail if there are missing links anywhere in the docs?

packages/documentation/package.json

packages/documentation/README.md

packages/documentation/astro.config.mjs

mkurapov · 2023-08-18T07:49:05Z

There are a number of things that I would like to discuss with the team before this PR can be finalised
What to do about the APIs section?

I don't mind having it just as part of the sidebar, or a separate page. Maybe someone else has a stronger opinion.

Better table design, will probably introduce a Table component or something

What would you like to see different?

Discussed before but found Mermaid code in the docs, so asking again, I thought we agreed to generate the diagrams and import?

I think we only have one mermaid diagram, so good for now. But it looks like from a search is that there is an astro x mermaid configuration : withastro/astro#4433

huijing · 2023-08-18T11:41:01Z

There are a number of things that I would like to discuss with the team before this PR can be finalised
What to do about the APIs section?

Max: I don't mind having it just as part of the sidebar, or a separate page. Maybe someone else has a stronger opinion.

Ok, let's try it as part of the sidebar for now. And see how you feel about the entire schema being on a single page instead of being split up.

Better table design, will probably introduce a Table component or something

Max: What would you like to see different?

Without further styling, right now because the generated markdown from schema contains some unbreakable lines (URLs and variable names), I need to add additional styles to tame the overflow or weirdness that comes from that.

Discussed before but found Mermaid code in the docs, so asking again, I thought we agreed to generate the diagrams and import?

Max: I think we only have one mermaid diagram, so good for now. But it looks like from a search is that there is an astro x mermaid configuration : withastro/astro#4433

I have looked at that and we won't be able to use that implementation ourselves because we are using the Starlight integration. If we do want this, I will most likely be pursuing this implementation instead (quoted from Astro discourse, which I've been pretty much living in this past month plus)

Haven’t tried it yet, but looks like rehype-mermaidjs may be able to do this? https://github.com/remcohaszing/rehype-mermaidjs

Astro supports rehype plugins via its regular config (https://docs.astro.build/en/guides/markdown-content/#markdown-plugins), so in theory that should be compatible. I’d be hesitant to add it as a built-in given it depends on Puppeteer, but we could definitey document usage if it works!

mkurapov · 2023-08-18T12:20:20Z

And see how you feel about the entire schema being on a single page instead of being split up.

Isn't it split up like rafiki.dev already? Or am I missing something?

re: other items, all makes sense!

huijing · 2023-08-18T12:24:52Z

And see how you feel about the entire schema being on a single page instead of being split up.

Isn't it split up like rafiki.dev already? Or am I missing something?

re: other items, all makes sense!

Ah, I should have been more clear. So, the current version of the APIs is a direct copy of the existing generated markdown files. The "new" version gives us what you would see in the "Schema types" page instead. I put them both in there for now so you all could compare the difference.

sabineschaller

Do we or do we not support Mermaid now? I think I saw just one diagram that was an svg in the docs.

Also, please note that I sent some design comments in the slack channel.

sabineschaller · 2023-08-23T11:22:27Z

packages/documentation/src/content/docs/concepts/accounting/assets.md

This is a duplicate and can be removed.

huijing · 2023-08-23T12:41:09Z

Do we or do we not support Mermaid now? I think I saw just one diagram that was an svg in the docs.

Also, please note that I sent some design comments in the slack channel.

Right now, for the Rafiki docs, I have not yet implemented it yet. I was hoping for some feedback on the whole Playwright thing here (copied from Slack):

OK FOLKS...erm...i'm going to try to put this succinctly...good news is...mermaid support seems to be working: https://deploy-preview-383--webmonetization-preview.netlify.app/docs/intro/web-monetization-flow/
it took me the better part of the day to figure out how to get it to deploy on netlify because it has a dependency on playwright.
soooooo this is the build log: https://app.netlify.com/sites/webmonetization-preview/deploys/64e5dac2011efd0008cbeac3
so under build u can see that a download of chromium is done, erm..i don't know if that's a good idea or not...cos deployment isn't really my thing. and i'm not sure how nicely this will play in rafiki cos rafiki does actually use netlify.

sabineschaller · 2023-08-23T12:58:51Z

I think once merge conflicts are resolved, this looks good. Thank you!

Update package.json and README Fix failing build Add mathjax support and update config Rebase with main and add asset page Resolve code scanning issue Attempt to style API tables Refresh graphql schemas Fix prettier issues Fix site logo issue on dark mode Sync theme across docs Update readme Update accounting tables and splash text Remove redundant asset page Resolve merge conflict

github-actions bot added pkg: documentation Changes in the documentation package. type: documentation (archived) Improvements or additions to documentation labels Aug 17, 2023

github-advanced-security bot found potential problems Aug 17, 2023

View reviewed changes

packages/documentation/src/components/docs/LargeImg/LargeImg.jsx Fixed Show fixed Hide fixed

mkurapov reviewed Aug 17, 2023

View reviewed changes

huijing force-pushed the chj/1739/migrate-to-starlight branch from 2460175 to 97dfb08 Compare August 18, 2023 12:07

huijing changed the title ~~Migrate documentation to Starlight~~ feat(documentation): Migrate documentation to Starlight Aug 18, 2023

huijing changed the title ~~feat(documentation): Migrate documentation to Starlight~~ feat(documentation): migrate documentation to Starlight Aug 18, 2023

huijing force-pushed the chj/1739/migrate-to-starlight branch 3 times, most recently from 94ee016 to da7ced9 Compare August 22, 2023 10:54

sabineschaller reviewed Aug 23, 2023

View reviewed changes

huijing force-pushed the chj/1739/migrate-to-starlight branch from 702d51d to 91e5b68 Compare August 23, 2023 14:04

sabineschaller approved these changes Aug 23, 2023

View reviewed changes

huijing merged commit f180415 into main Aug 23, 2023
23 of 24 checks passed

huijing deleted the chj/1739/migrate-to-starlight branch August 23, 2023 14:27

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(documentation): migrate documentation to Starlight #1742

feat(documentation): migrate documentation to Starlight #1742

huijing commented Aug 17, 2023

netlify bot commented Aug 17, 2023 •

edited

Loading

mkurapov left a comment

mkurapov Aug 17, 2023

mkurapov Aug 17, 2023

mkurapov Aug 17, 2023

mkurapov commented Aug 18, 2023

huijing commented Aug 18, 2023

mkurapov commented Aug 18, 2023 •

edited

Loading

huijing commented Aug 18, 2023

sabineschaller left a comment

sabineschaller Aug 23, 2023

huijing commented Aug 23, 2023

sabineschaller commented Aug 23, 2023

feat(documentation): migrate documentation to Starlight #1742

feat(documentation): migrate documentation to Starlight #1742

Conversation

huijing commented Aug 17, 2023

Changes proposed in this pull request

Context

Checklist

netlify bot commented Aug 17, 2023 • edited Loading

✅ Deploy Preview for brilliant-pasca-3e80ec canceled.

mkurapov left a comment

Choose a reason for hiding this comment

mkurapov Aug 17, 2023

Choose a reason for hiding this comment

mkurapov Aug 17, 2023

Choose a reason for hiding this comment

mkurapov Aug 17, 2023

Choose a reason for hiding this comment

mkurapov commented Aug 18, 2023

huijing commented Aug 18, 2023

mkurapov commented Aug 18, 2023 • edited Loading

huijing commented Aug 18, 2023

sabineschaller left a comment

Choose a reason for hiding this comment

sabineschaller Aug 23, 2023

Choose a reason for hiding this comment

huijing commented Aug 23, 2023

sabineschaller commented Aug 23, 2023

netlify bot commented Aug 17, 2023 •

edited

Loading

mkurapov commented Aug 18, 2023 •

edited

Loading