React 通过注释自动生成文档

最近找了一些文档的生成工具,结果发现了这个 React Styleguidist 可以通过注释,自动生成对应的文档,对于 react 库来说十分方便

安装

npm i -D react-styleguidist

// or

yarn add -D react-styleguidist

typescript 支持

npm i -D react-docgen-typescript

配置

这次的例子是使用 cra 来创建的项目,还有其他项目也是支持的 点击参考

在根文件夹下创建 styleguide.config.js 文件
可以使用如下的配置

const path = require('path')

const packagePath = path.resolve(
    __dirname,
    'package.json'
)
const packageFile = require(packagePath)

module.exports = {
    webpackConfig: require('./config/webpack.config'), // webpack 路径,可以用项目里的,也可以用webpack-blocks创建
    components: 'src/component/**.tsx', // 写入对应目录的文档
    propsParser: require('react-docgen-typescript').withCustomConfig(
        './tsconfig.json'
    ).parse, // 用来支持 tsx
    verbose: true, // 打印详细信息
    updateDocs(docs, file) {
        if (docs.doclets.version) {
            const version = packageFile.version

            docs.doclets.version = version
            docs.tags.version[0].description = version
        }

        return docs
    }, // 在使用 @version 时 使用 package.json 的 version
    version: packageFile.version, // 同上 使用 package.json 的 version
    usageMode: 'expand', // 自动打开文档的缩放
    pagePerSection: true, // 是否每页一个组件显示
    title: "文档名" // 文档名
}

更加具体的配置项可以点此参考

编写注释

例子 1:

import React from 'react';

interface IProps {
  /**
   * 用户名
   */
  name: string
  /**
   * 年龄
   */
  age?: number
  /**
   * 工作
   * @default doctor
   */
  work?: string
  /**
   * 修改名字
   * @param name
   */
  changeName?: (name: string) => void
}

/**
 * Person 组件
 * @version package.json
 * @visibleName Person 组件名称的显示
 */
function Person(props: IProps) {
  return <div>Person</div>
}

export default Person;

添加使用用例:

    import Person from './Person';
    <Person name="grewer"/>

图例:

例子 2:

import React from 'react';

interface IProps {
  type: 'submit' | 'button'

  /**
   * 尺寸
   * @deprecated 使用 size2 替代
   */
  size?: 'small' | 'default'

  /**
   * 新的尺寸
   * @since 1.1.0
   * @default large
   */
  size2?: 'small' | 'large'
}

/**
 * @link [antd button](https://ant.design/components/button-cn/) 可查看
 */
class Button extends React.Component<IProps, any> {
  static config = {
    desc: "这是 static 属性"
  }

  /**
   * 点击事件
   * @public
   */
  clickHandle = (ev: Event) => {
    console.log('!')
  }

  render(): React.ReactElement<any, string | React.JSXElementConstructor<any>> | string | number | {} | React.ReactNodeArray | React.ReactPortal | boolean | null | undefined {
    return <div>{this.props.children}</div>
  }
}

export default Button;

图例:

结果

使用如下命令,可以创建一个 web 服务,在线修改文档:

styleguidist server

使用如下命令,可以将文档项目打包

styleguidist build

如果库正好在 GitHub 上面,可是开通 GitHub Pages 功能,将文档包提交进 GitHub;
本例结果页面查看:

https://grewer.github.io/styleguidist-boilerplate/styleguide/

结语

当你使用 react 开发而又想要写文档的使用, React Styleguidist 绝对是最好的选择之一
而如果你的库在 GitHub 上,那么就能够立即生成你的文档站点

原文地址:https://www.cnblogs.com/Grewer/p/12168024.html

时间: 2024-10-03 14:55:45

React 通过注释自动生成文档的相关文章

使用 Swagger 自动生成 ASP.NET Core Web API 的文档、在线帮助测试文档(ASP.NET Core Web API 自动生成文档)

对于开发人员来说,构建一个消费应用程序时去了解各种各样的 API 是一个巨大的挑战.在你的 Web API 项目中使用 Swagger 的 .NET Core 封装 Swashbuckle 可以帮助你创建良好的文档和帮助页面. Swashbuckle 可以通过修改 Startup.cs 作为一组 NuGet 包方便的加入项目.Swashbuckle 是一个开源项目,为使用 ASP.NET Core MVC 构建的 Web APIs 生成 Swagger 文档.Swagger 是一个机器可读的 R

MVC WEB api 自动生成文档

最近在一直在用webapi做接口给移动端用.但是让我纠结的时候每次新加接口或者改动接口的时候,就需要重新修改文档这让我很是苦恼.无意中发现.webapi居然有自动生成文档的功能....真是看见了救星啊. 在看了一些资料后发现,如果你的开发环境比较老的话像VS2010 VS2008 这样的你可能需要手动在nuGet去安装一个新的组件, 需要安装这一个组件来进行配置,安装完成后会多一个文件夹(因为这个版本较新可能会有依赖版本冲突) 如果你是2013的版本的话你在创建项目的时候默认就会有这个文件夹,当

Eclipse自动生成文档注释

/** *这种格式的注释就是文档注释 */ 快捷键是alt+shift+j,将光标放在类名,变量名,方法名上,按快捷键.

修改XCode默认注释并自动生成文档

1.找到注释模板位置 首先右键Xcode -> 选项 -> 在Finder中打开 -> 右键 -> 显示包内容 Contents/Developer/Platforms/iPhoneOS.platform/Developer/Library/Xcode/Templates/File Templates/Source/Cocoa Touch Class.xctemplate 2.修改模板文件 这个目录下面有很多后缀名为Objective-C跟Swift的文件夹 我们先随便打开一个UI

.net core 自动生成文档

如下图自动生成显示接口文档注释

前端那点事儿——Tocify自动生成文档目录

今天偶然间看到文档服务器有一个动态目录功能,点击目录能跳转到指定的位置:窗口滑动也能自动更新目录的焦点. 效果 框架 原来使用的是一个开源的jquery-ui控件——tocify.js,它可以遍历页面,把指定的DOM元素抽取出来形成目录.下载地址参考gitub : [gfranko/jquery.tocify.js] 开发者可以直接下载zip包使用,压缩包里面的内容包括: demos 演示页面(里面有一个google的链接,访问会超时,去掉即可) images 可以忽略 libs 额外使用的文件

C#WebApi自动生成文档

1.效果图 2.在webApi项目,打开Nuget,搜索WebApiTestClient,安装WebApiTestClient,注意是给HelpPage的 3.打开引入WebApiTestClient后生成的HelpPageConfig.cs文件,将这行代码注释解开(原来生成的文件中,这行代码是被注释掉的) 4.打开项目的属性->打开“生成”标签页.勾选Xml文档文件,配置文档路径,要和上面的MapPath配置的路径一致(这里是App_Data.XmlDocument.xml),可以自行修改到别

使用Swagger自动生成文档

1.maven依赖 maven仓库(https://mvnrepository.com/)搜索springfox <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId&g

XCode生成文档

在写代码的时候,如果按照一定的规范在头文件里写上注释的话, 就可以利用Xcode的文档自动输出功能生成一份完整的HTML项目文档. 生成的格式和Apple Developer网站上的API文档几乎是一样的. 我们来看看如何利用Xcode生成项目文档.步骤:1. 在XCode里点击Project,然后点Add Target给项目添加一个TARGET 2. 在添加Target的弹出对话框里,选择Aggregate,点击Next,输入一个你喜欢的名字,点击Finish 3. 你会发现TARGETS下面