Typedoc + Vitepress 自动生成 typescript 项目文档

大洋彼岸的快递

已于 2023-09-28 16:17:12 修改

阅读量506

点赞数 1

分类专栏： vitepress+typedoc 文档文章标签： typescript javascript 前端

于 2023-09-28 13:18:13 首次发布

本文链接：https://blog.csdn.net/qq_31694733/article/details/133378190

版权

本文介绍了如何使用TypeDoc和Vitepress自动化typescript项目的文档生成。从创建typescript基础项目，配置TypeDoc和Vitepress，到设置自动生成Vitepress的侧边导航，一步步详细阐述了整个过程。最后，提到了通过GitHub Action自动化部署文档的可能性。

摘要由CSDN通过智能技术生成

前言

目前很多项目都在使用typescript作为项目的开发语言，但是一个项目没有相对应的文档，这对于其他使用该项目的开发者来说是一件相当痛苦的一件事情。同时，为了规范我们良好的开发行为，为项目写文档是一件不可或缺的事情。但是，作为程序员大部分的时间都耗在了开发程序的过程中，很难还有精力去写项目文档。

因此，我们可以使用一些包来帮我们实现生成文档的自动化，比如使用 npm run docs 使用一些这些类似的命令来帮助我们简化生成文档的繁琐操作。使用到的相关技术有：

项目基础目录搭建

创建一个typescript基础项目

创建一个空项目，也就是一个空文件夹，（比如我创建的是 myProject 文件夹），并初始化 node 项目：

	mkdir myProject
	cd myProject
	npm init -y

在该项目中我们需要安装 typescript，和你项目相关的包以及包对应的 npm types包，并初始化typescript.json。

	npm i typescript --save-dev
	npx tsc --init

配置 typescript.json，将以下内容复制粘贴到项目中生成的typescript.json文件：

	// tsconfig.json
	{
   
	  "compilerOptions": {
   
	    "target": "esnext",
	    "module": "esnext",
	    "moduleResolution": "node",
	    "importHelpers": true,
	    "experimentalDecorators": true,
	    "esModuleInterop": true,
	    "sourceMap": false,
	    "noEmit": true,
	    "strict": true,
	    "resolveJsonModule": true,
	    "jsx": "preserve"
	  },
	  "include": ["./src/*"]
	}

创建一个typescript项目，也就是在根目录下创建一个src文件夹，并在文件夹下创建4个文件：index.ts, A.ts, B.ts, C.ts:

	mkdir src

 A.ts:

	// src/A.ts

	/**
	 * Interface
	 */
	export interface AInterface {
   
	  /** attr1 */
	  key1: number;
	
	  /** attr2 */
	  key2: string;
	}
	
	/** Class */
	export class AClass {
   
	  /** Class attr */
	  prop1: number;
	
	  /** A's constructor */
	  constructor() {
   
	    this.prop1 = this.privateMethod1(1, 2);
	  }
	
	  /**
	   * Static methods
	   * @param names users names, a string array
	   * @returns return Promise object
	   */
	  static staticMethod1(names: string[]) {
   
	    return Promise.resolve(names);
	  }
	
	  /**
	   * private method
	   * @param param1 first parameter
	   * @param param2 second parameter
	   * @returns sum of two numbers
	   */
	  private privateMethod1(param1: number, param2: number) {
   
	    return param1 + param2;
	  }
	
	  /** public method */
	  publicMethod(param1: number, param2: number) {
   
	    return this.prop1 + param1 + param2;
	  }
	}
	
	/** type */
	export type MyType = 1 | 2 | 3 | 4;
	
	/**
	 * function
	 * @param param parameter
	 */
	export function myFunction(param: AInterface) {
   
	  return param;
	}
	
	/** Members that are not exported do not appear in the document */
	class MyClassNotExport {
   }

B.ts

	import * as THREE from "three";

	export class TestClassB {
   
	  /**
	   * Attr a
	   */
	  a: number;
	  /**
	   * Private Attr b
	   */
	  private b: number;
	
	  constructor() {
   
	    this.a = 123;
	    this.b = 777;
	  }
	
	  /**
	   * @public public function for create a three js scene
	   */
	  create3D() {
   
	    const scene = new THREE