狮身人面像的“意外的章节标题”——是 numpy 的问题吗？答案

【问题标题】：'Unexpected Section Title' with Sphinx -- is numpy the issue?狮身人面像的“意外的章节标题”——是 numpy 的问题吗？
【发布时间】：2010-06-23 11:48:35
【问题描述】：

运行时

sphinx-build . html/

在我的doc/ 目录中，我得到以下输出：

$ sphinx-build . html/
Running Sphinx v0.6.4
No builder selected, using default: html
loading pickled environment... done
building [html]: targets for 0 source files that are out of date
updating environment: 0 added, 1 changed, 0 removed
reading sources... [100%] index                 
reST markup error:
HIDDEN/PATH/matplotlib_visualization.py:docstring of simulator.extensions.matplotlib_visualization.beta:20: (SEVERE/4) Unexpected section title.

这个文件有 numpy 导入，经过一番研究，似乎 sphinx 使用的 RST 标记与记录 numpy 的方式存在问题。当我取出 numpy 导入时，html 构建良好。

解决此问题的最佳方法是什么？

【问题讨论】：

标签： python numpy python-sphinx restructuredtext

【解决方案1】：

这个主题讨论了这个主题： https://groups.google.com/d/msg/sphinx-users/MAFTlX8pAvk/B9hx7MuBVbIJ

皮埃尔 GM 说： “弗雷德里克，看起来您正在为您的文档使用 thw numpy 标准。考虑然后使用 Pauli Virtanen 实现的 numpydoc 扩展：可在此处获取：~~http://sphinx.googlecode.com/svn/contrib/trunk/~~ "

与 numpydoc 相关的当前信息： ~~https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt~~

关于 NumpyDoc 的移动信息：https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard

【讨论】：