docutils_react_docgen 1.1.0

示例

以下是显示所有在static/js/lib/my中的React模块的reStructuredText。每个模块的源链接相对于src选项

My JS/React Library
===================

.. contents:: Table of Contents

.. reactdocgen:: static/js/lib/my
        :src: https://bitbucket.org/.../my/src/tip

使用方法

在您的conf.py中，必须导入docutils_react_docgen

import docutils_react_docgen

在您的reStructuredText文档中包含reactdocgen指令，并在同一行上跟随react-docgen命令，后面跟着零个或多个选项行，然后是一个空行

.. reactdocgen::  /path/to/your/react/modules/ [react-docgen options]
    :option: value

这将转换输出为

react-docgen /path/to/your/react/modules/ [react-docgen options]

将重构文本插入到指令的位置。

react-docgen 允许您过滤要从中提取元数据的模块。请参阅

react-docgen --help

有关 react-docgen 命令行选项的解释。

每个模块都显示一个标题，显示模块名称（该名称可能出现在目录中），然后可选地跟随一个指向其源代码的链接，然后是其描述，然后是按字母顺序在定义列表中显示的属性。

选项

每个选项都显示其默认值。

exclude

default

使用此选项来过滤输出中出现的模块。

如果提供，则使用 python 的 re 模块将此正则表达式编译成模式。然后，如果模式在模块的描述中找到（使用 re.search），则将模块排除在输出之外。

include

default

使用此选项来过滤输出中出现的模块。

如果提供，则使用 python 的 re 模块将此正则表达式编译成模式。然后，只有当模式在模块的描述中找到（使用 re.search）时，模块才包含在输出中。

module_description_missing

default: 模块文档字符串缺失！

当模块的“描述”键值空时显示的字符串。

module_prop_description_missing

default: 属性文档字符串缺失！

当属性的“描述”键值空时显示的字符串。

module_underline_character

default: -

模块标题的下划线字符。

path_index

default: 0

路径参数的索引。

此索引是传递给指令的参数字符串中路径参数之前的参数数量。

当使用 project_base 设置时，指令使用 path_index 从其调用时的参数列表中识别路径参数。默认索引 0 表示路径参数是列表中的第一个。

更改此选项如果想要传递额外的参数给 react-docgen，这些参数在路径参数之前。

show_prop_type

default: False

如果为 True，则显示属性类型名称。

src

default

如果为空，则每个模块不显示链接。

如果不为空，则是链接到源代码时使用的前缀。URL 是前缀后跟“/”后跟模块文件名。

tab_size

default: 4

替换每个制表符字符的空格字符数。

use_commonjs_module_name

default: True

如果为 True，则从给定目录开始递归搜索 CommonJS 包，向上遍历目录树至根目录。

如果为 False，或者（如果为 True 且）找不到 bower.json 或 package.json，则模块名称将显示为其文件名而不是其 CommonJS 模块名称。

更改默认选项

所有选项的默认值可以直接更改。例如

import docutils_react_docgen
docutils_react_docgen.DEFAULT_OPTIONS['module_description_missing'] = ''

设置

react_docgen

default: react-docgen

要运行的 react-docgen 命令。

使用此设置提供 react-docgen 可执行文件的位置。默认情况下，假设 react-docgen 在 PATH 中。

此设置可以包含空格，因此可以调用带有一些前置选项的 react-docgen 的其他实现。

project_base

default: None

运行时项目的基地址。

在动态构建环境中使用此设置，以建立项目的绝对地址。

通常，您会切换到项目的基本目录（其中包含 setup.py）并运行

python setup.py build_sphinx

然而，一些构建环境是动态创建的。在某些情况下，事先可能不知道当前目录或项目与它的关系。在这些情况下，除非您告诉它如何，否则指令无法找到您的 React 文件进行处理。

只要你知道conf.py相对于项目基准的位置，就可以通过Python的内置__file__属性和os.path方法，在conf.py中设置project_base。

当此设置不为None（注意空字符串"不等于"None），并且指令的路径参数是相对地址时，指令将使用项目基准添加前缀来构建绝对路径。

path = os.path.abspath(os.path.join(
        SETTINGS['project_base'],
        path_argument))

rst_output

默认：None（没有单独的输出文件）

仅保存指令生成的rst的单独输出文件的完整路径。

当不为None时，每次执行指令都会创建输出文件。

当JavaScript源中有rst错误时，sphinx会报告错误的行号。使用此选项可以在单独的输出文件中找到给定行号处的错误。

更改设置

所有设置值都可以直接更改。例如，要设置react-docgen的路径

import docutils_react_docgen
react_docgen = './static/js/node_modules/react-docgen/bin/react-docgen.js'
docutils_react_docgen.SETTINGS['react_docgen'] = react_docgen

要使项目基准绝对，假设conf.py位于相对于项目基准的doc/中，而React模块位于static/js/lib/

然后在您的conf.py中

import docutils_react_docgen
import os
docutils_react_docgen.SETTINGS['project_base'] = os.path.join(
        '../',
        os.path.dirname(__file__))

然后在您的.rst文件中

.. react-docgen:: static/js/lib

提供自定义格式化程序

首先创建一个模块，继承Formatter和ReactDocgen，并注册您的指令

import docutils_react_docgen
from docutils.parsers import rst

class MyFormatter(docutils_react_docgen.Formatter):
    ... overwrite methods as necessary

class MyDirective(docutils_react_docgen.ReactDocgen):
    formatter_class = MyFormatter

rst.directives.register_directive('mydirective', MyDirective)

格式化器类将按如下方式调用

rst = self.formatter_class(options, dirname).run(doc_dict)

options

指令选项的字典。

dirname

搜索CommonJS包的路径。

doc_dict

从react-docgen返回的JSON blob加载的模块元数据的字典。键是模块文件名，值是React模块元数据的字典。

run()方法必须返回包含所需restructured text的字符串。

最后，确保conf.py导入了包含您的指令的模块