From 084b321e6a086fbed8ba2c0cb1e6c942d25329fd Mon Sep 17 00:00:00 2001 From: Philipp Kunz Date: Fri, 12 Apr 2024 15:28:55 +0200 Subject: [PATCH] fix(core): update --- npmextra.json | 20 +++-- package.json | 22 +++-- readme.hints.md | 5 ++ readme.md | 123 +++++++++++++++------------- ts/00_commitinfo_data.ts | 4 +- ts/aidocs_classes/projectcontext.ts | 7 ++ ts/aidocs_classes/readme.ts | 4 +- 7 files changed, 107 insertions(+), 78 deletions(-) create mode 100644 readme.hints.md diff --git a/npmextra.json b/npmextra.json index 5d26bf8..b90fe5c 100644 --- a/npmextra.json +++ b/npmextra.json @@ -9,18 +9,22 @@ "npmPackagename": "@git.zone/tsdoc", "license": "MIT", "projectDomain": "git.zone", - "description": "An advanced TypeScript documentation tool leveraging AI for enhanced insights and automated documentation generation.", + "description": "An advanced TypeScript documentation tool leveraging AI for enhanced insights and automated documentation generation, with capabilities for automated and enhanced documentation creation tailor-made for TypeScript projects.", "keywords": [ "TypeScript", - "documentation generation", + "documentation", "AI-enhanced documentation", - "automated documentation", + "automated documentation generation", "code analysis", - "type annotations", - "continuous integration documentation", - "markdown", - "CLI tool", - "software development tool" + "development tool", + "CLI utility", + "API documentation", + "developer productivity", + "code insights", + "integrated development environment tooling", + "code quality enhancement", + "project documentation", + "documentation automation" ] } }, diff --git a/package.json b/package.json index e13795f..0edfe75 100644 --- a/package.json +++ b/package.json @@ -2,7 +2,7 @@ "name": "@git.zone/tsdoc", "version": "1.1.16", "private": false, - "description": "An advanced TypeScript documentation tool leveraging AI for enhanced insights and automated documentation generation.", + "description": "An advanced TypeScript documentation tool leveraging AI for enhanced insights and automated documentation generation, with capabilities for automated and enhanced documentation creation tailor-made for TypeScript projects.", "main": "dist_ts/index.js", "typings": "dist_ts/index.d.ts", "type": "module", @@ -55,14 +55,18 @@ ], "keywords": [ "TypeScript", - "documentation generation", + "documentation", "AI-enhanced documentation", - "automated documentation", + "automated documentation generation", "code analysis", - "type annotations", - "continuous integration documentation", - "markdown", - "CLI tool", - "software development tool" + "development tool", + "CLI utility", + "API documentation", + "developer productivity", + "code insights", + "integrated development environment tooling", + "code quality enhancement", + "project documentation", + "documentation automation" ] -} +} \ No newline at end of file diff --git a/readme.hints.md b/readme.hints.md new file mode 100644 index 0000000..2d0653e --- /dev/null +++ b/readme.hints.md @@ -0,0 +1,5 @@ +* module needs to be installed globally +* alternatively can be used through npx, if installed locally +* cli parameters are concluded from ./ts/cli.ts +* this module is not intended for API use. +* Read carefully through the TypeScript files. Don't make stuff up. \ No newline at end of file diff --git a/readme.md b/readme.md index 57f7aa7..07ad4fb 100644 --- a/readme.md +++ b/readme.md @@ -1,85 +1,92 @@ # @git.zone/tsdoc -A TypeScript documentation tool with extensive features including AI-driven documentation enhancements. +An advanced TypeScript documentation tool that leverages AI for enhanced insights and automated documentation generation. ## Install -To install `@git.zone/tsdoc`, use npm (Node Package Manager). First, ensure you have Node.js installed on your system. Then, open a terminal and execute the following command: +To install `@git.zone/tsdoc`, you have two options depending on your usage preference: globally for CLI use or locally within your project for use through NPX. To install globally, run: -```bash -npm install @git.zone/tsdoc --save +```sh +npm install -g @git.zone/tsdoc ``` -This command downloads and installs `@git.zone/tsdoc`, adding it to your project's dependencies. +For local installation within your project, use: + +```sh +npm install --save @git.zone/tsdoc +``` + +You can then use the tool through NPX if installed locally: + +```sh +npx tsdoc +``` ## Usage -The usage section for `@git.zone/tsdoc` aims to guide you through leveraging the tool's capabilities for enhancing your TypeScript project documentation with AI-driven optimizations. Complete usage instructions exceed the space constraints here but include essential setup steps, examples, recommended practices, and how to integrate `@git.zone/tsdoc` into your project effectively. +`@git.zone/tsdoc` is a tool designed to improve the process of generating documentation for TypeScript projects. It combines the capabilities of Typedoc with AI-powered features to automatically generate insights and enhance the quality of your API documentation without manual intervention. -### Getting Started -First, ensure you import `@git.zone/tsdoc` functionalities into your project. Start by importing necessary functions or classes provided by the module in your TypeScript file: +To get started, after installation, navigate to the root directory of your TypeScript project where your `tsconfig.json` is located and run: ```typescript import { runCli } from '@git.zone/tsdoc'; + +// Initialize and run the CLI +runCli().then(() => { + console.log('Documentation generation complete!'); +}).catch((error) => { + console.error('Failed to generate documentation:', error); +}); ``` -### Basic Documentation Generation -`@git.zone/tsdoc` simplifies the generation of robust documentation for TypeScript projects. Initiate documentation generation by invoking the `runCli` method or through the CLI tool provided: +### Generating Documentation +`@git.zone/tsdoc` provides a command-line interface to generate documentation directly from your TypeScript source files. The CLI uses information from your TypeScript configuration and the source files to create comprehensive documentation. -```typescript -// Programmatically -await runCli(); +Once `tsdoc` is installed globally, you can run the following command in the root of your TypeScript project: -// Or using the CLI directly -tsdoc generate +```sh +tsdoc ``` -This process involves scanning for TypeScript annotations and comments to produce detailed documentation. +This command analyzes your TypeScript project, extracts type information, and generates documentation pages as HTML or Markdown. You can customize the output format and specify additional options via command line parameters or by editing `tsdoc` configuration files. -### Advanced Features -To get the most out of `@git.zone/tsdoc`, explore its AI-driven features designed to enhance the documentation further: +### Command Line Parameters +The CLI tool reads options from `./ts/cli.ts`. Command line parameters allow you to customize the behavior of `tsdoc`. For more detailed usage, run: -- **AI-Assisted Commenting**: Utilizes AI to suggest comments for complex code sections, improving understandability. -- **Documentation Quality Analysis**: Employs AI algorithms to evaluate and suggest improvements for your project's documentation, aiming for clarity, completeness, and effectiveness. - -### Continuous Integration -Integrate documentation generation into your continuous integration pipeline to automate the creation and updating of documentation with each code change. This approach ensures your documentation remains up-to-date and relevant. - -### Example: Documenting a TypeScript Module -Consider a module that provides basic arithmetic operations. Here's how you might document it using `@git.zone/tsdoc`: - -```typescript -/** - * A simple arithmetic calculator class. - */ -export class Calculator { - /** - * Adds two numbers. - * @param a The first number. - * @param b The second number. - * @returns The sum of `a` and `b`. - */ - add(a: number, b: number): number { - return a + b; - } - - /** - * Subtracts the second number from the first. - * @param a The first number. - * @param b The second number. - * @returns The difference of `a` and `b`. - */ - subtract(a: number, b: number): number { - return a - b; - } -} +```sh +tsdoc --help ``` -By including detailed comments and utilizing TypeScript's type system, you provide `@git.zone/tsdoc` with the information needed to generate comprehensive documentation for each method, including parameters and return types. +This will display a list of available commands and options, such as specifying the output directory for the generated documentation or enabling/disabling certain features of the documentation generator. + +### Examples +Below is an example of how to use `tsdoc` to generate documentation with custom options: + +```sh +tsdoc --output docs/api --format html +``` +This command generates HTML documentation for your project and places it in the `docs/api` directory. + +### Additional Features +Beyond basic documentation generation, `tsdoc` integrates AI-powered analysis to enrich the documentation automatically. This feature helps by providing insights into complex types, documenting patterns used within your codebase, and suggesting improvements for better maintainability and readability of your documentation. + +**Note:** `tsdoc` is designed for use with projects adhering to modern TypeScript conventions. Ensure your project structure and TypeScript configuration are compatible for optimal results. + +### Integration with CI/CD +`@git.zone/tsdoc` can be integrated into your CI/CD pipelines to automatically generate and update documentation as part of your build process. This ensures that your API documentation is always up-to-date with your codebase. + +Here's an example configuration snippet for a CI workflow: + +```yml +steps: + - name: Install tsdoc + run: npm install -g @git.zone/tsdoc + + - name: Generate Documentation + run: tsdoc +``` + +Remember to replace placeholders and adjust paths as necessary depending on your CI provider and project configuration. ### Conclusion -Incorporating `@git.zone/tsdoc` into your TypeScript project not only streamlines the documentation process but leverages AI to enhance the quality and effectiveness of your project's documentation. Follow the suggested practices and explore the advanced features to fully utilize this powerful tool. - -For further information and more detailed instructions on using the advanced features of `@git.zone/tsdoc`, please consult the official documentation. - -(Note: This usage section is a foundational guide; please refer to the full documentation of `@git.zone/tsdoc` for detailed instructions and advanced usage scenarios.) +`@git.zone/tsdoc` is a powerful tool that leverages the best of Typedoc and AI to streamline the documentation process for TypeScript projects. By automating the generation of insightful and comprehensive documentation, it enhances developer productivity and improves the quality of project documentation. ## License and Legal Information diff --git a/ts/00_commitinfo_data.ts b/ts/00_commitinfo_data.ts index de9faaa..79c25d5 100644 --- a/ts/00_commitinfo_data.ts +++ b/ts/00_commitinfo_data.ts @@ -3,6 +3,6 @@ */ export const commitinfo = { name: '@git.zone/tsdoc', - version: '1.1.16', - description: 'An advanced TypeScript documentation tool leveraging AI for enhanced insights and automated documentation generation.' + version: '1.1.17', + description: 'An advanced TypeScript documentation tool leveraging AI for enhanced insights and automated documentation generation, with capabilities for automated and enhanced documentation creation tailor-made for TypeScript projects.' } diff --git a/ts/aidocs_classes/projectcontext.ts b/ts/aidocs_classes/projectcontext.ts index d024e1b..8e65f16 100644 --- a/ts/aidocs_classes/projectcontext.ts +++ b/ts/aidocs_classes/projectcontext.ts @@ -19,6 +19,11 @@ export class ProjectContext { plugins.path.join(this.projectDir, 'readme.md'), this.projectDir ); + + const smartfilesReadmeHints = await plugins.smartfile.SmartFile.fromFilePath( + plugins.path.join(this.projectDir, 'readme.hints.md'), + this.projectDir + ); const smartfilesNpmextraJSON = await plugins.smartfile.SmartFile.fromFilePath( plugins.path.join(this.projectDir, 'npmextra.json'), this.projectDir @@ -34,6 +39,7 @@ export class ProjectContext { return { smartfilePackageJSON, smartfilesReadme, + smartfilesReadmeHints, smartfilesNpmextraJSON, smartfilesMod, smartfilesTest, @@ -59,6 +65,7 @@ ${smartfile.contents.toString()} let context = await this.convertFilesToContext([ files.smartfilePackageJSON, files.smartfilesReadme, + files.smartfilesReadmeHints, files.smartfilesNpmextraJSON, ...files.smartfilesMod, ...files.smartfilesTest, diff --git a/ts/aidocs_classes/readme.ts b/ts/aidocs_classes/readme.ts index fd68b04..0a5f4d4 100644 --- a/ts/aidocs_classes/readme.ts +++ b/ts/aidocs_classes/readme.ts @@ -59,7 +59,9 @@ The Readme should follow the following template: Don't include any licensing information. This will be added in a later step. Avoid "in conclusions". - npmextra.json has a tsdocs section that provides valuable information about module ideas. + Good to know: + * npmextra.json contains overall module information. + * readme.hints.md provides valuable hints about module ideas. ] `, contextString,