如何为 NumPy 文档做出贡献#

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

文档团队会议#

NumPy 社区制定了改进其文档的坚定目标。我们在 Zoom 上定期举行文档会议（日期在numpy-discussion 邮件列表上公布 ），欢迎大家。如果您有疑问或需要有人指导您完成第一步，请联系我们 - 我们很乐意为您提供帮助。会议记录在 hackmd.io 上记录 并存储在NumPy Archive 存储库中。

需要什么#

NumPy 文档涵盖了详细信息。 API 参考文档是 在构建文档时直接从代码中的文档字符串生成的。尽管我们对向用户公开的每个函数和类都有大部分完整的参考文档，但其中一些函数和类缺乏使用示例。

我们缺少的是范围更广的文档——教程、操作方法和解释。报告缺陷是另一种贡献方式。我们两者都讨论。

贡献修复#

我们渴望了解并修复文档缺陷。但为了解决最大的问题，我们最终不得不推迟或忽略一些错误报告。以下是要消除的最佳缺陷。

最重要的是技术错误——文档字符串缺少参数，函数/参数/方法的错误描述等等。其他“结构性”缺陷（例如断开的链接）也得到优先考虑。所有这些修复都很容易确认并实施。 如果您知道如何执行此操作，则可以提交包含修复程序的拉取请求 (PR) ；否则请提出问题。

拼写错误和拼写错误属于较低级别；我们欢迎听到这些问题，但可能无法立即修复它们。这些也可以作为拉取请求或问题来处理。

明显的措辞错误（例如遗漏“不”）属于拼写错误类别，但其他改写（即使是语法）也需要进行判断，这提高了标准。首先将修复作为问题提出来进行测试。

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

贡献新页面#

您在使用我们的文档时遇到的挫折是我们解决问题的最佳指南。

如果您编写了一个缺失的文档，那么您就加入了开源的前线，但只是让我们知道缺失了什么，这就是一个有意义的贡献。如果您想撰写文档，请通过邮件列表表达您的想法以获得进一步的想法和反馈。如果您想提醒我们存在差距， 请提出问题。请参阅 此问题的示例。

如果您正在寻找主题，我们的正式文档路线图是 NumPy 增强提案 (NEP)、 NEP 44 - 重构 NumPy 文档。它确定了我们的文档需要帮助的领域，并列出了我们希望看到的一些补充内容，包括Jupyter 笔记本。

文档框架#

编写有用的文档有一些公式，四个公式几乎涵盖了所有内容。有四个公式，因为文档有四种类别 - tutorial、、和。文档以这种方式划分的见解属于 Daniele Procida 和他的Diátaxis Framework。当您开始撰写一份文件或提出一份文件时，请记住该文件属于以下哪种类型。how-to guideexplanationreference

NumPy 教程#

除了属于 NumPy 源代码树一部分的文档之外，您还可以将 Jupyter Notebook 格式的内容提交到 NumPy 教程页面。这套教程和教育材料旨在由 NumPy 项目提供高质量的资源，既可用于自学，也可用于课堂教学。这些资源是在单独的 GitHub 存储库 numpy-tutorials中开发的，您可以在其中查看现有笔记本、打开问题以建议新主题或将您自己的教程作为拉取请求提交。

更多关于贡献#

如果英语不是您的母语，或者您只能拿出一个草稿，请不要担心。开源是社区的努力。尽力而为——我们将帮助解决问题。

图像和现实生活中的数据使文本更具吸引力和力量，但请确保您使用的内容已获得适当的许可并可用。在这里，即使是一个粗略的艺术想法也可以被其他人打磨。

目前，NumPy 唯一接受的数据格式是其他 Python 科学库（如 pandas、SciPy 或 Matplotlib）也使用的数据格式。我们正在开发一个包来接受更多格式；联系我们了解详情。

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

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

间接贡献#

如果您遇到对 NumPy 文档有用的外部材料，请通过提出问题让我们知道。

您不必在这里为 NumPy 做出贡献。如果您在博客上撰写教程、创建 YouTube 视频或在 Stack Overflow 和其他网站上回答问题，那么您就做出了贡献。

文档风格#

用户文档#

  • 一般来说，我们 的用户指南遵循Google 开发者文档风格指南。

  • NumPy 风格控制以下情况：

    • Google 没有任何指导，或者

    • 我们不喜欢使用 Google 风格

    我们目前的规则：

    • 遵循 的先例，我们将索引复数为索引而不是 索引numpy.indices。

    • 为了保持一致性，我们还将矩阵复数为矩阵。

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

  • 我们欢迎收到 关于我们应该添加到 NumPy 样式规则中的案例的提醒。

文档字符串#

当将Sphinx与 NumPy 约定结合使用时，您应该使用numpydoc扩展，以便正确处理您的文档字符串。例如，Sphinx 将从 Parameters文档字符串中提取该部分并将其转换为字段列表。使用还可以避免普通 Sphinx 在遇到 NumPy 文档字符串约定（例如sphinx 不希望在文档字符串中找到的节标题numpydoc（例如 ））时产生的 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 ) #

这是一个简单的简介。

详细信息请参见此处。欢迎多线。

参数：

  • num – 为参数 num 留下评论。

  • str – 为第二个参数留下注释。

返回：

为返回值留下评论。

对于行注释，您可以使用三个正斜杠。例如：

/**
 *  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.
};

这是它的渲染方式：

模板<类型名Tp , std :: size_t N >
类DoxyLimbo #

表示临时数字的模板。

不属于任何地方的整数类型的特化。它不支持任何实际类型。

参数 Tp :

整数的类型。要求是整数类型。

参数N ：

元素数量。

公共职能

多西林博()#

默认构造函数。不初始化任何内容。

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

设置复制边缘的默认行为。

const Tp *数据( ) #

返回 Limbo 的原始数据。

受保护的属性

Tp p_data [ N ] #

内嵌注释的示例。

常见的 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);

这是它的渲染方式：

无效doxy_reST_example (无效) #

注释块包含剩余标记。

一些代码示例：

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

该指令为单个类生成适当的输出。它采用标准项目、路径、大纲和无链接选项，以及成员、受保护成员、私有成员、undoc-成员、成员组和仅限成员选项：

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

查看doxygenclass 文档 <https://breathe.readthedocs.io/en/latest/class.html#class-example>_ 了解更多详细信息并查看其实际情况。

doxygennamespace

该指令为命名空间的内容生成适当的输出。它采用标准项目、路径、大纲和无链接选项，以及仅内容、成员、受保护成员、私有成员和 undoc-members 选项。要引用嵌套命名空间，必须提供完整的命名空间路径，例如 foo::bar 表示 foo 命名空间内的 bar 命名空间。

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

查看doxygennamespace 文档 以获取更多详细信息并查看其实际情况。

doxygengroup

该指令为 doxygen 组的内容生成适当的输出。 doxygen 组可以在源注释中使用特定的 doxygen 标记来声明，如 doxygen分组文档中所述。

它采用标准项目、路径、大纲和无链接选项，以及仅内容、成员、受保护成员、私有成员和 undoc-members 选项。

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

查看doxygengroup 文档 以获取更多详细信息并查看其实际情况。

文档阅读#

  • 领先的技术作家组织 Write the Docs举办会议、托管学习资源并运行 Slack 频道。

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

  • Software Carpentry 的使命是向研究人员教授软件。除了主持课程之外，该网站还解释了如何有效地表达想法。