evilmartians / astro-typedoc Goto Github PK

I'm going to build an Astro project to learn key features using their official tutorial:

https://docs.astro.build/en/tutorial/0-introduction/

TODO:

• Build a working Astro project

Now, the code works with a single entry point.

It's possible for code to have multiple of them, and we should check how to handle it the right way.
We may want to split navigation to avoid possible confusion, for example.

This task is for checking what can go wrong and fixing it.

• Adapt navigation - #36
• Make sure cross-module/cross-project links work - #37
• Fix folder names for Astro to make pages work - #38

https://github.com/kytta/eslint-plugin-node-import

Decide in which format config should be, its fields and options.
Can be dirty on early stage, but should be stable and documented later.

• Add config reference
• Document config in readme file
• Define the types for the config if needed/common practice

Check out https://astro.build

TODO:

• Go through the main sections
• Learn about integrations

Document how to work with integration, config fields, etc.

Prepare testing environments for following things:

1. Astro/starlight environment. To make sure pages are generating the right way

2. Stub TypeScript project. To have some controlled playground with typed project

3. Nanostores site environment. To have some less-controlled playground with real typed project

Add markdown content from typedoc-plugin-markdown to astro pages of types.

Now, frontmatter is hardcoded.
We need to make it configurable, because potential user may want to pass some additional data to use it in templates.

Astro uses YAML for frontmatters, so we'll need some Pojo to YAML library.
And find a good place to put it, mostly likely in page generating stage.

So API may look like this:

const astroTypedoc = initAstroTypedoc(config)
const reflections = await astroTypedoc.getReflections()
await astroTypedoc.generateDocs({
  reflections,
  outputFolder: 'src/pages/docs',
  frontmatter: {
    layout: resolve(__dirname, './layouts/CustomLayout.astro')
  }
})

Possible variations

1. atom/index.d.ts:100
2. ./atom/index.d.ts:100
3. nanostores/atom/index.d.ts:100

There is a solution that seems to be close to what we want:
https://starlight-typedoc-example.vercel.app/

I need to check how it works, and is there any possibility that we could improve this one to get what we want.

TODO:

• Run without any modifications on the sample TS project
• Check if it's possible to adjust the design -- adding tables, links

Integration should be able to generate navigation based on documented entities.

Also, we need to make sure that links in .md are all working and not leading to .md files

We have 3 potential user cases:

1. User which use this utility to create site with API docs
2. User which integrates API docs as a site section -- uses default layout partly
3. User which integrates API docs as a site section -- with completely custom layout and styles, but still can reuse some of the default styles

Now docs are looking like plain unstyled HTML, which seems raw.
This issue is for adding a some default styled layout which doesn't hurt viewer's eyes.

Basically, task is about creating an Astro layout template, and pass its path as a default layout field in generated docs frontmatter.

• Navigation sidebar
• Header
• Search
• Doc page styles
• Themization variables
• Guide on theming in Readme
• Mobile version

Good intro to docs is the key to open source project promotion. We should add it after adding good styling out-of-the-box.

• Check out my slides about open source promotion
• Add screenshot which will explain tool only by image (TypeDoc example in a classic Starlight design)
• Improve the first sentence which describe the tool
• Add npm install and other simple steps to install the tool

Build Astro plugin for generating pages based on exported types.
They may have no content but should have their own URL.

TypeDoc seems to be a good candidate for generating documentation from type definitions and TSDoc comments.

I need to check its input formats, output formats, and restrictions.

TODO:

• Go through docs
• Run TypeDoc on some TS projects
• Check outputs
• Try modifying outputs
• Check ai's scripts

Starlight is astro-based tool for documentation sites.

I need to check what it's capable of, plugins system, alternatives.

TODO:

• Go through docs
• Check for alternatives
• Check integrations and how easy/hard they to add

Now integration works only with untouched TypeDoc reflections tree.

We need to make sure it will work if we change something in it.

The task is also about finding the best way to modify a tree: it can be tree-walker-callback, which is passed as a parameter to integration or some utility function that will generate a tree first, allow the user to modify it, and then integration consumes the modified tree.

Basically, user should be able to pass typedoc config into the integration config.

• Check TypeDoc options and decide which options should be configurable

Generated navigation should follow Starlight API:

type SidebarItem = {
  label: string;
  translations?: Record<string, string>;
} & (
  | { link: string }
  | { items: SidebarItem[]; collapsed?: boolean }
  | {
      autogenerate: { directory: string; collapsed?: boolean };
      collapsed?: boolean;
    }
);

It either will be a separate utility like in starlight-typedoc or just implicit under the hood thing that will work out of the box by default.

Check if there are any issues related to v2-v3 versions of Astro and fix them.

• Run integration on v3 Astro site
• Check for errors
• Fix errors if present or close issue if everything is fine