fix: fixes generation issue with the Astro srcDir option

[charlesLoder]

First, I just found this tool and it's fantastic! Thanks for all the hard work.

Describe the pull request

Adds support for respecting the srcDir option from the Astro Config

Why

I have a lib that I work on and the docs are in the repo like this:

.
├── CHANGELOG.md
├── CONTRIBUTING.md
├── LICENSE.md
├── README.md
├── changelog.sh
├── dist
├── docs (the source of the docs)
├── node_modules
├── package-lock.json
├── package.json
├── src (the library source)
└── test

and my docs/astro.config.mjs looks like this:

import { defineConfig } from "astro/config";
import starlight from "@astrojs/starlight";
import starlightTypeDoc, { typeDocSidebarGroup } from "starlight-typedoc";

// https://astro.build/config
export default defineConfig({
  root: "./docs",
  srcDir: "./docs/src",
  integrations: [
    starlight({
      plugins: [
        starlightTypeDoc({
          entryPoints: ["./src/index.ts"],
          tsconfig: "./.config/tsconfig.json"
        })
      ],
      sidebar: [
        {
          label: "Getting started",
          autogenerate: { directory: "getting-started" }
        },
        // Add the generated sidebar group to the sidebar.
        typeDocSidebarGroup
      ]
    })
  ]
});

This was causing starlight-typedoc to generate the markdown files in src (the library source) and not in docs/src the srcDir in the config.

How

The changes were implemented primarily by passing in the whole AstroConfig to generateTypeDoc function, and updating the outputPath:

- const outputPath = path.join('src/content/docs', outputDirectory)
+ const outputPath = path.join(`${config.srcDir.pathname}/content/docs`, outputDirectory)

Additional comments

(1) I've never used workspaces, and the changes in pnpm-lock are confusing to me. Let me know if I should revert those changes
(2) I feel...eh about the tests, but I wasn't sure if there was a better way to fake the AstroConfig.

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
starlight-typedoc	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Jul 16, 2024 7:45am
starlight-typedoc-example	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Jul 16, 2024 7:45am

[HiDeoo]

Thanks a lot for your feedback and pull request, super appreciated 🙌

The changes definitely make sense and looks good to me. I only suggested a change to the approach to avoid issues on Windows. Regarding the tests, definitely not the best but I think this should be enough for now, and maybe we can switch to an E2E test in the future if we see the need.

Let me know what you think about the suggested changes but the overall PR looks good to me 👍

[HiDeoo]

Suggested change

	const outputPath = path.join(`${config.srcDir.pathname}/content/docs`, outputDirectory)
	const outputPath = path.join(url.fileURLToPath(config.srcDir), 'content/docs', outputDirectory)

Tested the change on Windows, and this approach would fail (probably because the driver letter is recognized as the protocol) so instead of getting something like C:\Users\…, you get \C:\Users\… which errors during the generation process.

Note that this would require an extra import url from 'node:url' at the top.

[charlesLoder]

I always forget about Windows. Thanks for the catch

[HiDeoo]

Suggested change

	config: AstroConfig = starlightTypeDocAstroConfig as AstroConfig,
	config: Partial<AstroConfig> = starlightTypeDocAstroConfig,

As it's only for tests, let's move the cast in this function so it avoids the need to do it in tests.

[HiDeoo]

Suggested change

	config,
	config as AstroConfig,

[HiDeoo]

Suggested change

	{ srcDir: new URL('docs/src', import.meta.url) } as AstroConfig,
	{ srcDir: new URL('www/src', import.meta.url) },

And we should be able to remove this cast.

Let's also use www/src for the test as docs is already part of the path, maybe it's a bit more obvious to use a totally different directory?

[charlesLoder]

I just copied my own setup (which gets confusing), so www works for me

[HiDeoo]

Suggested change

	expect(mkdirSyncSpy.mock.calls[0]?.[0].toString()).toMatch(/docs[/\\]src[/\\]content[/\\]docs[/\\]api$/)
	expect(mkdirSyncSpy.mock.calls[0]?.[0].toString()).toMatch(/www[/\\]src[/\\]content[/\\]docs[/\\]api$/)

To match the previous change.

[HiDeoo]

This should indeed be reverted considering the scope of the changes.

[charlesLoder]

For the git history, I

• reset the original commit
• unstaged pnpm-lock
• re-commited with the same message
• incorporated the new commits.

[HiDeoo]

Thanks for the fast update, everything looks perfect to me 👍

Great job on that pull request, thanks for you contribution.