Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Adopt typedoc for API docs #66

Merged
merged 17 commits into from
Feb 2, 2024
Merged

Adopt typedoc for API docs #66

merged 17 commits into from
Feb 2, 2024

Conversation

DmitrySharabin
Copy link
Member

@DmitrySharabin DmitrySharabin commented Jan 18, 2024 •
edited
Loading

Closes #63.

The docs are much better now! 🤩

https://deploy-preview-66--madata.netlify.app/api/

@netlify Netlify
Copy link

netlify bot commented Jan 18, 2024 •
edited
Loading

✅ Deploy Preview for madata ready!

Name Link
🔨 Latest commit 1249375
🔍 Latest deploy log https://app.netlify.com/sites/madata/deploys/65bd33665b848200088a9a9b
😎 Deploy Preview https://deploy-preview-66--madata.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

@LeaVerou
Copy link
Contributor

Thanks for working on this!
Some Qs:

  • Is there a way to use Prism instead of whatever this is using for syntax highlighting?
  • It's also parsing our README.md and displaying it, but not any of the other READMEs or other Markdown files. I wonder if that's possible to enable somehow.
  • How can we make CSS customizations? Might be a good idea to include a CSS stub file

@DmitrySharabin
Copy link
Member Author

Thanks for working on this!

Some Qs:

  • Is there a way to use Prism instead of whatever this is using for syntax highlighting?

  • It's also parsing our README.md and displaying it, but not any of the other READMEs or other Markdown files. I wonder if that's possible to enable somehow.

  • How can we make CSS customizations? Might be a good idea to include a CSS stub file

Good questions. Will dig into typedoc a bit. There might be something in there that we can use.

@DmitrySharabin
Copy link
Member Author

How can we make CSS customizations? Might be a good idea to include a CSS stub file

We can have a custom CSS file, which will be referenced in the typedoc.json file.

How would we call it? api.css?

Where should we place it? In the root? In the _build folder? Inside _include? Somewhere else? It will be copied into the assets directory and referenced by the API docs theme.

@DmitrySharabin
Copy link
Member Author

It's also parsing our README.md and displaying it, but not any of the other READMEs or other Markdown files. I wonder if that's possible to enable somehow.

This is planned to be in the core (hopefully) soon.

Until then, there is a plugin that might help us get the desired result. But there is much hand work involved. Should we try to use it?

@LeaVerou
Copy link
Contributor

How can we make CSS customizations? Might be a good idea to include a CSS stub file

We can have a custom CSS file, which will be referenced in the typedoc.json file.

How would we call it? api.css?

Where should we place it? In the root? In the _build folder? Inside _include? Somewhere else? It will be copied into the assets directory and referenced by the API docs theme.

We can start with api.css in the root for now, and move it when we move the website CSS

@LeaVerou
Copy link
Contributor

It's also parsing our README.md and displaying it, but not any of the other READMEs or other Markdown files. I wonder if that's possible to enable somehow.

This is planned to be in the core (hopefully) soon.

Until then, there is a plugin that might help us get the desired result. But there is much hand work involved. Should we try to use it?

We don't need typedoc for our own docs, but it would be nice to have it for the individual READMEs within each backend/format/etc. Can we use a different MD file than README.md for the root? It seems very weird to duplicate our homepage content there.

Would it be easier to automate the handwork involved?

@DmitrySharabin
Copy link
Member Author

Can we use a different MD file than README.md for the root? It seems very weird to duplicate our homepage content there.

We can. I just pushed the commit, which allows us to use API.md (we can rename and re-locate it later if needed) as a custom index (root) page for the API docs.

Would it be easier to automate the handwork involved?

I'm sure it would. 😅 Will give it a try.

@DmitrySharabin
Copy link
Member Author

Digging a bit further into the problem of generating doc pages from our READMEs, I learned that the plugin I was going to use for this doesn't work with the latest version of typedoc. 😭 Nor do other plugins from which that one was forked. I will try to find alternative solutions. 🤞

@DmitrySharabin
Add human-readable name
fbe3d20
@DmitrySharabin
Improve docs output
17e20ef
@DmitrySharabin
Add support for the abstract tag
9c34d79
@DmitrySharabin
Merge branch 'main' into adapt-typedoc
e8945d0
@DmitrySharabin
Add watch:docs command
574d887
@DmitrySharabin
Workaround to calm down the TS compiler when working with JS files (see
5f37d6a 
microsoft/TypeScript#27436 (comment))
@DmitrySharabin
Add options to customize syntax highlight themes
f456f75 
For the list of all supported themes, see https://shiki.matsu.io/themes#bundled-themes.
@DmitrySharabin
Switch to the JS config file for more versatility
05043d8
@DmitrySharabin
Hide the protected and external filters since we don't have such modi…
a26dc56 
…fiers
@DmitrySharabin
Add (partial) support for Prism
1249375 
In Typedoc, we can use no extensibility point [1] to replace the built-in syntax highlighter (Shiki) with Prism. The only way to do that is to write a custom theme that (somehow) uses another syntax highlighter or doesn't highlight code blocks at all. I tried but failed — there's a ton of stuff to know to be able to do that (at least from my perspective).

However, we can make the built-in markdown plugin (Marked) use a custom highlight function instead of the one that calls the Typedoc built-in syntax highlighter. That means that our markdown files and code blocks in the code comments (Typedoc supports markdown in comments) can be highlighted by Prism.

[1] https://discord.com/channels/508357248330760243/829307039447515176/1202594912051273848
@LeaVerou
Copy link
Contributor

LeaVerou commented Feb 2, 2024

Dmitry, let's merge this since it's clearly better than the current state, then we can improve it later. Do you agree?

@DmitrySharabin
Copy link
Member Author

Dmitry, let's merge this since it's clearly better than the current state, then we can improve it later. Do you agree?

Absolutely! I almost lost my mind trying to find a way to make it work we wanted. 😅

@DmitrySharabin DmitrySharabin merged commit 1aed450 into main Feb 2, 2024
4 checks passed
@DmitrySharabin DmitrySharabin deleted the adapt-typedoc branch February 2, 2024 19:05
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@LeaVerou LeaVerou Awaiting requested review from LeaVerou

Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

[chore] Adopt typedoc for API docs
2 participants
@DmitrySharabin @LeaVerou