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:

npm install -g @git.zone/tsdoc

Usage with npx

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

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.

tsdoc

Example

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

tsdoc typedoc --publicSubdir docs

Example

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.

tsdoc aidoc

Example

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.

tsdoc test

Example

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

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

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.

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

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

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

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.

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

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