fix(core): update

This commit is contained in:
Philipp Kunz 2024-04-12 15:28:55 +02:00
parent cf1cfbd647
commit 084b321e6a
7 changed files with 107 additions and 78 deletions

View File

@ -9,18 +9,22 @@
"npmPackagename": "@git.zone/tsdoc", "npmPackagename": "@git.zone/tsdoc",
"license": "MIT", "license": "MIT",
"projectDomain": "git.zone", "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": [ "keywords": [
"TypeScript", "TypeScript",
"documentation generation", "documentation",
"AI-enhanced documentation", "AI-enhanced documentation",
"automated documentation", "automated documentation generation",
"code analysis", "code analysis",
"type annotations", "development tool",
"continuous integration documentation", "CLI utility",
"markdown", "API documentation",
"CLI tool", "developer productivity",
"software development tool" "code insights",
"integrated development environment tooling",
"code quality enhancement",
"project documentation",
"documentation automation"
] ]
} }
}, },

View File

@ -2,7 +2,7 @@
"name": "@git.zone/tsdoc", "name": "@git.zone/tsdoc",
"version": "1.1.16", "version": "1.1.16",
"private": false, "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", "main": "dist_ts/index.js",
"typings": "dist_ts/index.d.ts", "typings": "dist_ts/index.d.ts",
"type": "module", "type": "module",
@ -55,14 +55,18 @@
], ],
"keywords": [ "keywords": [
"TypeScript", "TypeScript",
"documentation generation", "documentation",
"AI-enhanced documentation", "AI-enhanced documentation",
"automated documentation", "automated documentation generation",
"code analysis", "code analysis",
"type annotations", "development tool",
"continuous integration documentation", "CLI utility",
"markdown", "API documentation",
"CLI tool", "developer productivity",
"software development tool" "code insights",
"integrated development environment tooling",
"code quality enhancement",
"project documentation",
"documentation automation"
] ]
} }

5
readme.hints.md Normal file
View File

@ -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.

123
readme.md
View File

@ -1,85 +1,92 @@
# @git.zone/tsdoc # @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 ## 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 ```sh
npm install @git.zone/tsdoc --save 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 ## 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 To get started, after installation, navigate to the root directory of your TypeScript project where your `tsconfig.json` is located and run:
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:
```typescript ```typescript
import { runCli } from '@git.zone/tsdoc'; 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 ### Generating Documentation
`@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: `@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 Once `tsdoc` is installed globally, you can run the following command in the root of your TypeScript project:
// Programmatically
await runCli();
// Or using the CLI directly ```sh
tsdoc generate 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 ### Command Line Parameters
To get the most out of `@git.zone/tsdoc`, explore its AI-driven features designed to enhance the documentation further: 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. ```sh
- **Documentation Quality Analysis**: Employs AI algorithms to evaluate and suggest improvements for your project's documentation, aiming for clarity, completeness, and effectiveness. tsdoc --help
### 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;
}
}
``` ```
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 ### 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. `@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.
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.)
## License and Legal Information ## License and Legal Information

View File

@ -3,6 +3,6 @@
*/ */
export const commitinfo = { export const commitinfo = {
name: '@git.zone/tsdoc', name: '@git.zone/tsdoc',
version: '1.1.16', version: '1.1.17',
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.'
} }

View File

@ -19,6 +19,11 @@ export class ProjectContext {
plugins.path.join(this.projectDir, 'readme.md'), plugins.path.join(this.projectDir, 'readme.md'),
this.projectDir 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( const smartfilesNpmextraJSON = await plugins.smartfile.SmartFile.fromFilePath(
plugins.path.join(this.projectDir, 'npmextra.json'), plugins.path.join(this.projectDir, 'npmextra.json'),
this.projectDir this.projectDir
@ -34,6 +39,7 @@ export class ProjectContext {
return { return {
smartfilePackageJSON, smartfilePackageJSON,
smartfilesReadme, smartfilesReadme,
smartfilesReadmeHints,
smartfilesNpmextraJSON, smartfilesNpmextraJSON,
smartfilesMod, smartfilesMod,
smartfilesTest, smartfilesTest,
@ -59,6 +65,7 @@ ${smartfile.contents.toString()}
let context = await this.convertFilesToContext([ let context = await this.convertFilesToContext([
files.smartfilePackageJSON, files.smartfilePackageJSON,
files.smartfilesReadme, files.smartfilesReadme,
files.smartfilesReadmeHints,
files.smartfilesNpmextraJSON, files.smartfilesNpmextraJSON,
...files.smartfilesMod, ...files.smartfilesMod,
...files.smartfilesTest, ...files.smartfilesTest,

View File

@ -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. Don't include any licensing information. This will be added in a later step.
Avoid "in conclusions". 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, contextString,