Giters

facebook / docusaurus

Easy to maintain open source documentation websites.

Home Page:https://docusaurus.io

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

Missing documentation for theme components

pixelass opened this issue · comments

commented

Have you read the Contributing Guidelines on issues?

Description

Note

As a developer
I want a documentation of core components
So that I know what I can use and how it works

I found these rather vague documentations:

Temporary solutions

image

Self-service

  • I'd be willing to address this documentation request myself.
commented

Remember that Docusaurus core value proposition is "focus on your content", ie writing Markdown files, not React code.

A theme has potentially hundreds of components, many of them considered as internal implementation details that you are not necessarily supposed to "reuse" in your code.

It's not planned to document theme components in our documentation, apart a few exceptions (<Admonition>, <CodeBlock> for example).

Theme component refactors will happen so don't expect component names and props to be stable, unless they are officially documented.

If you want to know which undocumented theme components are considered "stable", and are not likely to break on minor releases, run this:

npm run swizzle @docusaurus/theme-classic -- --list

You'll get a brief description of the component as well.

CleanShot 2024-05-02 at 19 23 01@2x

It's documented here:

https://docusaurus.io/docs/swizzling#which-component-should-i-swizzle

commented

Well for a documentation framework that is a bold statement. The components are used in the base setup so why wouldn't they be documented.

I understand that it is focused on documentation that is written in markdown, but not providing any API documentation for the components is a rather questionable decision.

Note

Don't get me wrong, I am happy that you are putting work into a rather nice experience and easy to use documentation framework and getting our tsdoc genereated markdown in and adjusting the sidebar was rather straight forward and intuitive. 👍

I do however expect components to be documented. It isn't only useful for end-users but also those that want to engage and help by working on open source software.

Additional, with the help of AI it should be super easy to generate some good documentation for all those components or even provide some basic docblocks: https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-theme-classic/src/theme/Heading/index.tsx

That being said, I'm going to have to accept your decission to not docuemnt the components.
Feel free to close this issue to prevent issue flooding.

Cheers.

commented

Well for a documentation framework that is a bold statement. The components are used in the base setup so why wouldn't they be documented.

Because they are internal.

Those that are part of our public API surface are documented. We commit to not do breaking changes on public API surface. We don't on private API surface. Things that are undocumented can break.

Similarly we don't document all the internal node APIs we use, including @docusaurus/utils packages etc. Although Docusaurus relies on those, it's not for mainstream usage.

If we had to document everything, it would take us a lot of time. And we'd have to maintain retro compatibility for those APIs (or break our commitment to semver). It would be impossible to make Docusaurus evolve if we have that level of friction to ship new features and refactors.

but not providing any API documentation for the components is a rather questionable decision.

No, this is on purpose. Even if we had the bandwidth to document every single component (which we haven't), we don't want to because it makes it very difficult to do any theme refactor in the future without shipping a new major version. By not documenting things, we allow ourselves to not consider everything as part of our API surface, which enables us to move faster.

To understand better what we consider being semver compatible, read this:
https://docusaurus.io/community/release-process#public-api-surface