feat: typedoc cli packages

[cabljac]

• Add in dart typedoc generator package
• Add in node wrapper for typedoc package
• Fix tab content in production

Docs still need to be completed for all the new features.

[cabljac]

This file will be expanded on, but doesn't appear in the sidebar of our docs yet

[Salakar]

Invalid comment

[gemini-code-assist]

Summary of Changes

I've implemented significant new features to enhance documentation generation, primarily by integrating Typedoc support. This includes developing a new Dart-based command-line interface (CLI) package and a Node.js wrapper to facilitate the generation of API reference documentation from Typedoc comments. Additionally, I've updated the core API to handle this new reference configuration and provided comprehensive documentation on how to use these new tools. A minor fix for tab content display in the production environment has also been included.

Highlights

• New Dart CLI Package for Typedoc: I've introduced a new Dart CLI package specifically designed for docs.page. This package enables the generation of documentation directly from Typedoc JSON output, streamlining the process of creating API reference documentation.
• Node.js Wrapper for CLI: To ensure cross-platform compatibility and ease of use, I've created a Node.js wrapper for the Dart CLI package. This allows users to run the docs_page commands seamlessly across different operating systems.
• API Service Enhancement for Reference Config: The core api service has been enhanced to support referenceConfig. This new capability allows the system to properly ingest and display the structured documentation generated by Typedoc, integrating it smoothly into the existing documentation framework.
• New Typedoc Documentation: I've added a comprehensive typedoc.mdx documentation file. This file provides clear, step-by-step instructions on how to leverage the new Typedoc support, guiding users through the setup and generation process.
• Production Tab Content Fix: A fix has been implemented for an issue affecting tab content rendering in the production environment of the website, ensuring that all tabbed content displays correctly for users.
• Dynamic Sidebar Integration for References: The website/app/components/Sidebar.tsx has been updated to dynamically display the newly generated reference documentation. This means that once Typedoc documentation is generated, it will automatically appear in the sidebar, improving navigation and discoverability.

Changelog

• .prettierignore
  • Added packages/dart_cli/example and packages/dart_cli/docs to the ignore list.
• api/src/controllers/raw.ts
  • Removed an unnecessary newline for minor formatting adjustment.
• api/src/utils/bundle.ts
  • Introduced a new type definition called References.
  • Added a referenceConfig property to the Bundle class, allowing it to store reference configuration data.
  • Initialized the referenceConfig property to null in the Bundle class constructor.
  • Ensured that githubContents.referenceConfig is assigned to this.referenceConfig after content is fetched from GitHub.
  • Included referenceConfig in the object returned by the toObject() method.
• api/src/utils/github.ts
  • Imported the new References type.
  • Extended the PageContentsQuery type to include an optional referenceConfig field.
  • Added referenceConfig: References | null to the Contents type.
  • Modified the GraphQL query to fetch referenceConfig from docs.refs.json.
  • Implemented logic to parse the docs.refs.json content, including error handling for parsing failures.
  • Included the parsed referenceConfig in the Contents object returned by getGitHubContents.
• docs/typedoc.mdx
  • Added a new documentation file explaining how to set up and use Typedoc support with docs.page, including steps for generating typedoc.json and configuring docs.json or docs.yaml.
• packages/dart_cli/.gitignore
  • Added docs_page to the .gitignore file.
• packages/dart_cli/CHANGELOG.md
  • Updated the changelog to reflect version 0.0.1 (prerelease), 0.0.2 (added help command and improved init), and 0.0.3 (fixed docs.refs.json check in typedoc command).
• packages/dart_cli/LICENSE
  • Added the Apache License, Version 2.0 to the package.
• packages/dart_cli/README.md
  • Updated the README to describe the package's purpose for Docs.page, its pre-release status, and the init and typedoc commands.
• packages/dart_cli/bin/docs_page.dart
  • Refactored the main command-line interface logic to use a switch statement for better command handling.
  • Decoupled the createFiles logic into a separate src/init.dart file and imported it.
  • Integrated the typedoc command to process Typedoc JSON and generate documentation.
  • Added a help command to display usage information.
• packages/dart_cli/example/main.dart
  • Added a new example file demonstrating how to programmatically use the Typedoc generation functionality within the Dart CLI.
• packages/dart_cli/lib/src/docs_page_config.dart
  • Introduced DocsPageConfig and DocSearch classes for structured handling of docs.json, docs.yaml, and docs.toml configuration files.
  • Provided factory constructors to load configuration from a directory, supporting JSON, YAML, and TOML formats.
  • Added a method to overwrite configuration files in a directory, supporting JSON and YAML formats.
• packages/dart_cli/lib/src/docs_page_config.g.dart
  • Added a new file, automatically generated by json_serializable, providing JSON serialization/deserialization logic for DocsPageConfig and DocSearch classes.
• packages/dart_cli/lib/src/help.dart
  • Added a new file containing the displayHelp function, which outputs the CLI's supported commands and general information.
• packages/dart_cli/lib/src/init.dart
  • Added a new file encapsulating the createFiles logic for initializing a docs.page project.
  • Improved the init command to check for existing configuration files and to support generating either JSON or YAML config based on an environment variable.
  • Updated the default sidebar configuration to include a basic 'Home' link.
• packages/dart_cli/lib/src/typedoc.dart
  • Added new classes (Node, Group, Source, Comment, Tag) to represent the structure of Typedoc's JSON output.
  • Implemented getTypedocJson to read and parse the typedoc.json file.
  • Developed the generate function to process the Typedoc AST and create corresponding MDX documentation files.
  • Included helper functions like addRef to manage references, createDoc to generate individual documentation pages, and getGithubLink to create source links.
• packages/dart_cli/lib/src/typedoc.g.dart
  • Added a new file, automatically generated by json_serializable, providing JSON serialization/deserialization logic for the Typedoc AST classes.
• packages/dart_cli/pubspec.lock
  • Updated numerous package dependencies, reflecting the addition of new features and the build process for the Dart CLI, including json_annotation, json_serializable, toml, and yaml related packages.
• packages/dart_cli/pubspec.yaml
  • Updated the package description and version to 0.0.3.
  • Added json_serializable, json_annotation, toml, and yaml to the project dependencies.
  • Included build_runner in development dependencies for code generation.
  • Added a repository field pointing to the GitHub repository.
• packages/npx_cli/index.js
  • Added a new JavaScript file that serves as the entry point for the Node.js wrapper.
  • This script now spawns the Dart docs_page executable, passing command-line arguments and setting an environment variable to prefer JSON config format.
• packages/npx_cli/package.json
  • Renamed the package from @docs.page/init to @docs.page/cli.
  • Updated the package version.
  • Removed the typescript dependency, as the Node.js wrapper now directly executes the Dart binary.
  • Added a prepublish script to ensure the Dart binaries have executable permissions.
  • Updated the bin field to point to index.js and the files array to include binaries.
• packages/npx_cli/src/index.ts
  • Removed the old TypeScript source file for the init command, as its functionality has been migrated to the Dart CLI.
• packages/npx_cli/tsconfig.json
  • Removed the TypeScript configuration file, as the npx_cli package no longer uses TypeScript for its main entry point.
• packages/server/src/types.ts
  • Extended ConfigWithoutLocales, ConfigWithLocales, and OutputConfig interfaces to include reference?: string (for the root of reference paths) and typedocEntryDir?: string (for the Typedoc entry directory).
  • Modified BundleSuccess to include referenceConfig and defined the References type for structured reference data.
• website/app/components/DocsRefSwitch.tsx
  • Added a new React component that provides a UI switch between regular documentation and generated reference documentation, using icons and conditional styling.
• website/app/components/Sidebar.tsx
  • Imported the new DocsRefsSwitch component.
  • Retrieved references, referenceConfig, and frontmatter from the documentation context.
  • Implemented logic to format the referenceConfig by kind for organized display.
  • Integrated the DocsRefsSwitch into the sidebar.
  • Modified the sidebar rendering to dynamically display either the standard documentation links or the generated reference documentation based on the frontmatter.reference flag.
• website/app/components/mdx/GithubLink.tsx
  • Added a new MDX component, GithubLink, which generates a link to the source code on GitHub based on the provided title and source path.
• website/app/components/mdx/Tabs.tsx
  • Applied minor formatting adjustments by adding newlines within the extractTabItems and tab mapping sections.
• website/app/components/mdx/index.tsx
  • Imported and exported the new GithubLink component, making it available for use within MDX files.
• website/app/context.tsx
  • Modified the useBaseUrl hook to include the owner and repo in the base URL path when a custom domain is not in use, ensuring correct routing for non-custom domains.
• website/app/loaders/documentation.server.ts
  • Updated the DocumentationLoader type to include referenceConfig.
  • Ensured that referenceConfig is passed along with other documentation data when loading content on the server.
• website/app/utils/config.ts
  • Extended the ProjectConfig interface to include references (for the reference subdirectory name) and typedocEntryDir (for the Typedoc entry directory).
  • Set default values for references to 'API' and typedocEntryDir to 'src' in defaultConfig.
  • Updated the mergeConfig function to correctly merge these new configuration properties.
• yarn.lock
  • Updated various package versions across the project, reflecting changes in dependencies introduced by the new Dart CLI and its build requirements.

Activity

• cabljac commented on docs/typedoc.mdx, noting that the file would be expanded but was not yet in the sidebar.
• cabljac suggested an update to docs/typedoc.mdx, proposing the addition of a "references" field.
• cabljac suggested a change to packages/dart_cli/lib/src/typedoc.dart, specifically an error message related to a missing "references" field.
• Salakar commented on website/app/components/mdx/Tabs.tsx, stating "Invalid comment".
• Salakar raised a concern about the use of "q4" in website/app/components/mdx/Tabs.tsx, suggesting it might be inconsistent.
• Ehesp replied to Salakar's comment on website/app/components/mdx/Tabs.tsx, agreeing that the approach was inconsistent and that the check could likely be removed.
• Salakar followed up on the discussion regarding website/app/components/mdx/Tabs.tsx, advising to remove the change and sync with the main branch.