如何为 NumPy 文档做贡献#

本指南将帮助您决定要贡献什么以及如何将其提交到官方 NumPy 文档.

文档团队会议#

NumPy 社区已经设定了一个坚定的目标,即改进其文档.我们定期在 Zoom 上举行文档会议（日期在 numpy-discussion 邮件列表 上宣布）,欢迎所有人参加.如果您有任何问题或需要有人指导您完成第一步,请随时联系我们——我们很乐意帮忙.会议记录在 hackmd.io 上进行,并存储在 NumPy Archive 仓库 中.

需要什么#

The NumPy Documentation has the details covered. API reference documentation is generated directly from docstrings in the code when the documentation is built. Although we have mostly complete reference documentation for each function and class exposed to users, there is a lack of usage examples for some of them.

我们所缺乏的是范围更广的文档——教程、操作指南和解释.报告缺陷是另一种贡献方式.我们讨论这两者.

贡献修复#

我们渴望听到并修复文档缺陷.但为了解决最大的问题,我们最终不得不推迟或忽略一些错误报告.以下是最佳的缺陷修复目标.

首要任务是解决 技术不准确 问题——比如缺少参数的文档字符串、函数/参数/方法的错误描述等.其他”结构性”缺陷,如断开的链接,也优先处理.所有这些修复都很容易确认并实施.如果你知道如何操作,可以提交一个 pull request (PR) 进行修复;否则请 打开一个问题.

拼写错误和拼写错误 处于较低的位置;我们欢迎听到这些错误,但可能无法及时修复.这些也可以作为拉取请求或问题来处理.

明显的 用词 错误（比如漏掉一个”不”）属于错别字类别,但其他重写——即使是语法上的——也需要判断,这提高了门槛.首先通过将修复作为问题提出,来测试水域.

一些函数/对象,如 numpy.ndarray.transpose, numpy.array 等,在 C 扩展模块中定义,它们的文档字符串在 _add_newdocs.py 中单独定义.

贡献新页面#

您在使用我们文档时的挫败感是我们需要改进的最佳指南.

如果你编写缺失的文档,你将加入开源的前线,但仅仅让我们知道缺失了什么也是有意义的贡献.如果你想撰写文档,可以通过 邮件列表 运行你的想法以获得进一步的建议和反馈.如果你想提醒我们注意一个缺口,`打开一个问题 <numpy/numpy#issues>`__.查看 这个问题 作为一个例子.

如果你在寻找主题,我们的正式文档路线图是一个 NumPy 增强提案 (NEP),:ref:NEP44.它指出了我们文档需要帮助的领域,并列出了我们希望看到的几项新增内容,包括 Jupyter notebooks.

文档框架#

编写有用文档有一些公式,四个公式几乎涵盖了所有内容.有四个公式是因为有四种类型的文档 – 教程、操作指南、解释 和 参考.文档这样划分归功于 Daniele Procida 和他的 Diátaxis 框架.当你开始编写文档或提议编写时,请记住它属于这四种类型中的哪一种.

NumPy 教程#

除了作为NumPy源代码树一部分的文档外,您还可以将Jupyter Notebook格式的内容提交到 NumPy Tutorials 页面.这组教程和教育材料旨在通过NumPy项目提供高质量的资源,既适用于自学,也适用于教学课程.这些资源在一个单独的GitHub仓库 numpy-tutorials 中开发,您可以在那里查看现有的笔记本,打开问题以建议新主题或以拉取请求的形式提交您自己的教程.

更多关于贡献#

如果英语不是你的第一语言,或者你只能写出粗略的草稿,请不要担心.开源是一个社区的努力.尽你所能——我们会帮助解决问题的.

图像和真实数据使文本更加引人入胜和有力,但请确保您使用的内容已适当授权并可用.再次强调,即使是艺术作品的粗略想法也可以由他人完善.

目前,NumPy 接受的唯一数据格式是那些也被其他 Python 科学库（如 pandas、SciPy 或 Matplotlib）使用的格式.我们正在开发一个包以接受更多格式;请联系我们获取详细信息.

NumPy 文档保存在源代码树中.要将您的文档纳入文档库,您必须下载树,:ref:构建它,并提交一个拉取请求.如果 GitHub 和拉取请求对您来说是新的,请查看我们的 贡献者指南.

我们的标记语言是 reStructuredText (rST),它比 Markdown 更复杂.Sphinx,许多 Python 项目用来构建和链接项目文档的工具,将 rST 转换为 HTML 和其他格式.有关 rST 的更多信息,请参阅 Quick reStructuredText 指南 或 reStructuredText 入门

间接贡献#

如果你遇到外部材料,认为对NumPy文档有用的补充,请通过 opening an issue 告知我们.

你不必在这里贡献才能为 NumPy 做出贡献.如果你在博客上写教程、创建 YouTube 视频或在 Stack Overflow 和其他网站上回答问题,你就是在贡献.

文档风格#

用户文档#

  • 一般来说,我们遵循 Google 开发者文档风格指南 来编写用户指南.

  • NumPy 风格适用于以下情况:

    • Google 没有指导,或者

    • 我们倾向于不使用 Google 风格

    我们当前的规则:

    • 我们将 index 复数化为 indices 而不是 indexes,遵循 numpy.indices 的先例.

    • 为了保持一致性,我们也将 matrix 复数化为 matrices.

  • NumPy 或 Google 规则未能充分解决的语法问题由最新版《芝加哥格式手册》中”语法和用法”部分决定.

  • 我们欢迎被 提醒 到我们应该添加到 NumPy 风格规则的情况.

文档字符串#

在使用 Sphinx 结合 NumPy 约定时,你应该使用 numpydoc 扩展,以便正确处理你的文档字符串.例如,Sphinx 会从你的文档字符串中提取 Parameters 部分并将其转换为字段列表.使用 numpydoc 还可以避免在遇到像部分标题（例如 -------------）这样的 NumPy 文档字符串约定时,由普通 Sphinx 产生的 reStructuredText 错误.

它可以从以下位置获取:

请注意,在 NumPy 文档中,不需要在示例的开头进行 import numpy as np.

请使用 numpydoc 格式化标准 ,如他们的 示例 所示.

记录 C/C++ 代码#

NumPy 使用 Doxygen 解析格式化的 C/C++ 注释块.这会生成 XML 文件,这些文件由 Breathe 转换为 RST,然后由 Sphinx 使用.

完成文档编写过程需要三个步骤:

1. 编写注释块#

虽然还没有设定要遵循的注释风格,但由于与当前现有的非索引注释块的相似性,Javadoc 比其他注释风格更受欢迎.

备注

请参阅 “文档化代码”.

这是Javadoc风格的样例:

/**
 * This a simple brief.
 *
 * And the details goes here.
 * Multi lines are welcome.
 *
 * @param  num  leave a comment for parameter num.
 * @param  str  leave a comment for the second parameter.
 * @return      leave a comment for the returned value.
 */
int doxy_javadoc_example(int num, const char *str);

这里是它的呈现方式:

int doxy_javadoc_example(int num, const char *str)#

This a simple brief.

And the details goes here. Multi lines are welcome.

参数:

  • num – leave a comment for parameter num.

  • str – leave a comment for the second parameter.

返回:

leave a comment for the returned value.

对于行注释,你可以使用三斜杠.例如:

/**
 *  Template to represent limbo numbers.
 *
 *  Specializations for integer types that are part of nowhere.
 *  It doesn't support with any real types.
 *
 *  @param Tp Type of the integer. Required to be an integer type.
 *  @param N  Number of elements.
*/
template<typename Tp, std::size_t N>
class DoxyLimbo {
 public:
    /// Default constructor. Initialize nothing.
    DoxyLimbo();
    /// Set Default behavior for copy the limbo.
    DoxyLimbo(const DoxyLimbo<Tp, N> &l);
    /// Returns the raw data for the limbo.
    const Tp *data();
 protected:
    Tp p_data[N]; ///< Example for inline comment.
};

这里是它的呈现方式:

template<typename Tp, std::size_t N>
class DoxyLimbo#

Template to represent limbo numbers.

Specializations for integer types that are part of nowhere. It doesn’t support with any real types.

参数 Tp:

Type of the integer. Required to be an integer type.

参数 N:

Number of elements.

公共函数

DoxyLimbo()#

Default constructor. Initialize nothing.

DoxyLimbo(const DoxyLimbo<Tp, N> &l)#

Set Default behavior for copy the limbo.

const Tp *data()#

Returns the raw data for the limbo.

受保护的属性

Tp p_data[N]#

Example for inline comment.

常见的 Doxygen 标签:#

备注

更多标签/命令,请查看 https://www.doxygen.nl/manual/commands.html

@brief

开始一个作为简要描述的段落.默认情况下,文档块的第一句话会自动被视为简要描述,因为在doxygen配置中启用了 JAVADOC_AUTOBRIEF 选项.

@details

就像 @brief 开始一个简要描述一样,``@details`` 开始详细描述.你也可以开始一个新段落（空白行）,然后就不需要 @details 命令了.

@param

开始为一个名为 <parameter-name> 的函数参数描述,随后是对该参数的描述.检查参数的存在,如果此（或任何其他）参数的文档缺失或在函数声明或定义中不存在,则给出警告.

@return

开始一个函数的返回值描述.多个相邻的 @return 命令将被合并成一个段落.``@return`` 描述在遇到空白行或其他分节命令时结束.

@code/@endcode

开始/结束一个代码块.代码块与普通文本的处理方式不同.它被解释为源代码.

@rst/@endrst

开始/结束一个 reST 标记块.

示例#

看看下面的例子:

/**
 * A comment block contains reST markup.
 * @rst
 * .. note::
 *
 *   Thanks to Breathe_, we were able to bring it to Doxygen_
 *
 * Some code example::
 *
 *   int example(int x) {
 *       return x * 2;
 *   }
 * @endrst
 */
void doxy_reST_example(void);

这里是它的呈现方式:

void doxy_reST_example(void)#

注释块包含 reST 标记.

一些代码示例:int example(int x) { return x * 2; }

备注

多亏了 Breathe,我们才能够将其带到 Doxygen

2. 喂食 Doxygen#

并非所有头文件都会被自动收集.您必须在 Doxygen 的子配置文件中添加所需的 C/C++ 头文件路径.

子配置文件有一个独特的名称 .doxyfile,你通常可以在包含文档头文件的目录附近找到它.如果你想添加的头文件附近（2层深度内）没有配置文件,你需要创建一个新的配置文件.

子配置文件可以接受 Doxygen 的任何 配置选项,但不会覆盖或重新初始化任何配置选项,而是仅使用连接操作符 “+=”.例如:

# to specify certain headers
INPUT += @CUR_DIR/header1.h \
         @CUR_DIR/header2.h
# to add all headers in certain path
INPUT += @CUR_DIR/to/headers
# to define certain macros
PREDEFINED += C_MACRO(X)=X
# to enable certain branches
PREDEFINED += NPY_HAVE_FEATURE \
              NPY_HAVE_FEATURE2

备注

@CUR_DIR 是一个模板常量,返回子配置文件的当前目录路径.

3. 包含指令#

Breathe 提供了一系列自定义指令,允许将由 Doxygen 生成的文档转换为 reST 文件.

备注

更多信息,请查看”指令和配置变量”

常用指令:#

doxygenfunction

此指令生成单个函数的适当输出.函数名在项目中必须是唯一的.

.. doxygenfunction:: <function name>
    :outline:
    :no-link:

查看 示例 以了解其运行情况.

doxygenclass

此指令生成单个类的适当输出.它接受标准的项目、路径、大纲和无链接选项,并额外接受成员、受保护成员、私有成员、无文档成员、成员组和仅成员选项:

.. doxygenclass:: <class name>
   :members: [...]
   :protected-members:
   :private-members:
   :undoc-members:
   :membergroups: ...
   :members-only:
   :outline:
   :no-link:

查看 doxygenclass 文档 以获取更多详细信息并查看实际操作.

doxygennamespace

这个指令生成命名空间内容的适当输出.它接受标准的项目、路径、大纲和无链接选项,以及内容仅限、成员、受保护成员、私有成员和未记录成员选项.要引用嵌套的命名空间,必须提供完整的命名空间路径,例如 foo::bar 表示 foo 命名空间内的 bar 命名空间.

.. doxygennamespace:: <namespace>
   :content-only:
   :outline:
   :members:
   :protected-members:
   :private-members:
   :undoc-members:
   :no-link:

查看 doxygennamespace 文档 获取更多详细信息并查看实际操作.

doxygengroup

此指令生成doxygen组的适当输出.可以使用源注释中的特定doxygen标记声明doxygen组,如doxygen 分组文档 中所述.

它接受标准的项目、路径、大纲和无链接选项,并额外接受仅内容、成员、受保护成员、私有成员和未记录成员选项.

.. doxygengroup:: <group name>
   :content-only:
   :outline:
   :members:
   :protected-members:
   :private-members:
   :undoc-members:
   :no-link:
   :inner:

查看 doxygengroup 文档 以获取更多详细信息并查看实际操作.

Legacy 指令#

如果一个函数、模块或API处于*遗留*模式,这意味着它为了向后兼容而被保留,但不推荐在新代码中使用,你可以使用 .. legacy:: 指令.

默认情况下,如果没有参数,旧版指令将生成以下输出:

Legacy

这个子模块被认为是遗产,将不再接收更新.这也可能意味着它将在未来的 NumPy 版本中被移除.

我们强烈建议您也添加一条自定义消息,例如用新的API替换旧的API:

.. legacy::

   For more details, see :ref:`distutils-status-migration`.

此消息将被附加到默认消息中,并将创建以下输出:

Legacy

这个子模块被认为是遗产,将不再接收更新.这也可能意味着它将在未来的 NumPy 版本中被移除.更多详情请参见 numpy.distutils 的状态和迁移建议.

最后,如果你想提及一个函数、方法（或任何自定义对象）而不是一个 子模块 ,你可以使用一个可选参数:

.. legacy:: function

这将创建以下输出:

Legacy

此功能被视为遗留功能,将不再接收更新.这也可能意味着它将在未来的 NumPy 版本中被移除.

文档阅读#

  • 技术作家领域的领先组织,`Write the Docs <https://www.writethedocs.org/>`__,举办会议,提供学习资源,并运营一个Slack频道.

  • “每个工程师也是一名作家,” 谷歌的 技术写作资源集合 说,其中包括为开发者在规划和撰写文档提供的免费在线课程.

  • Software Carpentry 的任务是教授研究人员软件.除了托管课程外,该网站还解释了如何有效地呈现想法.

On this page