tsdoc/readme.md

# @git.zone/tsdoc

An advanced TypeScript documentation tool using AI to generate and enhance documentation for TypeScript projects.

## Install

To install `@git.zone/tsdoc`, you can either install it globally or use it with `npx`.

### Global Installation

You can install `@git.zone/tsdoc` globally on your system using npm:

```bash
npm install -g @git.zone/tsdoc
```

### Usage with npx

If you prefer not to install it globally, you can use it with `npx`:

```bash
npx @git.zone/tsdoc <command>
```

## Usage

`@git.zone/tsdoc` provides a comprehensive CLI tool and advanced AI-enhanced features to generate and enhance documentation for your TypeScript projects.

### Using the CLI

The primary interface for `@git.zone/tsdoc` is through its command-line tool. Below, we'll explore the different commands available and provide examples of how to use them.

### Commands

#### `tsdoc` - Auto-detect Documentation Format

The standard command will automatically detect the documentation format of your project and generate the appropriate documentation.

```bash
tsdoc
```

### Example

```typescript
// In a TypeScript project, run the above command.
```

#### `tsdoc typedoc` - Generate Documentation using TypeDoc

The `typedoc` command will generate documentation compliant with the TypeDoc format.

```bash
tsdoc typedoc --publicSubdir docs
```

### Example

```typescript
import * as plugins from '@push.rocks/smartfile';

const tsconfigPath = plugins.path.join(__dirname, 'tsconfig.json');
const outputPath = plugins.path.join(__dirname, 'docs');

await plugins.smartshellInstance.exec(
  `typedoc --tsconfig ${tsconfigPath} --out ${outputPath} index.ts`,
);
```

#### `tsdoc aidoc` - Generate AI-Enhanced Documentation

The `aidoc` command will use AI to generate an enhanced README and update your project description.

```bash
tsdoc aidoc
```

### Example

```typescript
import { AiDoc } from '@git.zone/tsdoc';

(async () => {
  const aidoc = new AiDoc();
  await aidoc.start();
  await aidoc.buildReadme('./');
  await aidoc.buildDescription('./');
})();
```

#### `tsdoc test` - Test Your Documentation Setup

The `test` command will test your current documentation setup, ensuring everything is configured correctly.

```bash
tsdoc test
```

### Example

```typescript
import * as plugins from '@git.zone/tsdoc';

await plugins.runCli().catch((err) => {
  console.error(err);
  process.exit(1);
});
```

## Features in Depth

### Using Plugins

`@git.zone/tsdoc` extensively uses plugins to extend its capabilities.

### Available Plugins

- **npmextra**: Manage npm project-related configurations.
- **qenv**: Environment variable management.
- **smartai**: AI integration.
- **smartcli**: CLI helper.
- **smartdelay**: Simple delay utility.
- **smartfile**: File system utilities.
- **smartinteract**: Interaction helper.
- **smartlog**: Logging utility.
- **smartlogDestinationLocal**: Local file destination for logging.
- **smartpath**: Path utilities.
- **smartshell**: Shell command execution.
- **typedoc**: Documentation generation.

### Example Usage of Plugins

#### Path Management

```typescript
import * as path from 'path';

const packageDir = path.join(__dirname, '../');
const cwd = process.cwd();
const binDir = path.join(packageDir, './node_modules/.bin');
const assetsDir = path.join(packageDir, './assets');
const publicDir = path.join(cwd, './public');
const tsDir = path.join(cwd, './ts');
const tsconfigFile = path.join(assetsDir, './tsconfig.json');
const typedocOptionsFile = path.join(assetsDir, './typedoc.json');
```

#### Logging

```typescript
import * as plugins from './plugins';

const logger = new plugins.smartlog.Smartlog({
  logContext: {
    company: 'Some Company',
    companyunit: 'Some CompanyUnit',
    containerName: 'Some Containername',
    environment: 'local',
    runtime: 'node',
    zone: 'gitzone',
  },
  minimumLogLevel: 'silly',
});

logger.addLogDestination(new plugins.smartlogDestinationLocal.DestinationLocal());
```

## Advanced Usage

### Using `TypeDoc` Class

The `TypeDoc` class provides utility methods to compile TypeScript documentation.

```typescript
import { TypeDoc } from '@git.zone/tsdoc/classes.typedoc';

const typeDocInstance = new TypeDoc(paths.cwd);

await typeDocInstance.compile({
  publicSubdir: 'docs',
});
```

### Using `AiDoc` Class

The `AiDoc` class integrates with AI services to enhance your documentation.

#### Initializing and Using AI

```typescript
import { AiDoc } from '@git.zone/tsdoc';

const aiDoc = new AiDoc({ OPENAI_TOKEN: 'your-openai-token' });

await aiDoc.start();
await aiDoc.buildReadme('./');
await aiDoc.buildDescription('./');
```

#### Retrieving AI Tokens

```typescript
import * as plugins from '@git.zone/tsdoc/plugins';

const qenv = new plugins.qenv.Qenv();
const openaiToken = await qenv.getEnvVarOnDemand('OPENAI_TOKEN');
```

### Testing

The provided tests demonstrate how to verify the functionality of the `@git.zone/tsdoc` tool.

#### Example Test Script

```typescript
import { expect, tap } from '@push.rocks/tapbundle';
import * as tsdoc from '../ts/index';

tap.test('should create AiDoc instance', async () => {
  const aidoc = new tsdoc.AiDoc({ OPENAI_TOKEN: 'dummy-token' });
  expect(aidoc).toBeInstanceOf(tsdoc.AiDoc);
});

tap.test('should start AiDoc', async () => {
  const aidoc = new tsdoc.AiDoc({ OPENAI_TOKEN: 'dummy-token' });
  await aidoc.start();
  await aidoc.buildReadme('./');
  await aidoc.buildDescription('./');
});

tap.start();
```

### Internals

The `@git.zone/tsdoc` consists of several internal classes and utilities that streamline its functionality.

#### File Paths Management

Located in `ts/paths.ts`, the file defines various directories and file paths used by the tool.

```typescript
import * as plugins from './plugins';

export const packageDir = plugins.path.join(
  plugins.smartpath.get.dirnameFromImportMetaUrl(import.meta.url),
  '../',
);
export const cwd = process.cwd();
export const binDir = plugins.path.join(packageDir, './node_modules/.bin');
export const assetsDir = plugins.path.join(packageDir, './assets');
export const publicDir = plugins.path.join(cwd, './public');
export const tsDir = plugins.path.join(cwd, './ts');
export const tsconfigFile = plugins.path.join(assetsDir, './tsconfig.json');
export const typedocOptionsFile = plugins.path.join(assetsDir, './typedoc.json');
```

#### Utility Commands

Define utility commands that streamline various processes.

##### Example: SmartCLI Usage

```typescript
// Import required modules and plugins
import * as plugins from './plugins';
import * as paths from './paths';

// TypeDoc and AiDoc classes
import { TypeDoc } from './classes.typedoc';
import { AiDoc } from './classes.aidoc';

// Export a run function
export const run = async () => {
  const tsdocCli = new plugins.smartcli.Smartcli();

  tsdocCli.standardCommand().subscribe(async (argvArg) => {
    switch (true) {
      case await TypeDoc.isTypeDocDir(paths.cwd):
        tsdocCli.triggerCommand('typedoc', argvArg);
        break;
      default:
        console.error(`Cannot determine docs format at ${paths.cwd}`);
    }
  });

  tsdocCli.addCommand('typedoc').subscribe(async (argvArg) => {
    const typeDocInstance = new TypeDoc(paths.cwd);
    await typeDocInstance.compile({
      publicSubdir: argvArg.publicSubdir,
    });
  });

  tsdocCli.addCommand('aidoc').subscribe(async (argvArg) => {
    const aidocInstance = new AiDoc(argvArg);
    await aidocInstance.start();
    await aidocInstance.buildReadme(paths.cwd);
    await aidocInstance.buildDescription(paths.cwd);
  });

  tsdocCli.startParse();
};
```

By leveraging these functionalities, you can configure and extend `@git.zone/tsdoc` to fit your specific documentation generation needs.

### Further Enhancements

The `@git.zone/tsdoc` tool is designed to be extensible. Explore the source files and plugins to add more functionality or integrate with other tools as needed. This README provides an extensive overview of the commands and features but it's always beneficial to dive into the source code to understand the intricacies and potential customizations. Happy documenting!

## License and Legal Information

This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository.

**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

### Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.

### Company Information

Task Venture Capital GmbH  
Registered at District court Bremen HRB 35230 HB, Germany

For any legal inquiries or if you require further information, please contact us via email at hello@task.vc.

By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.