<p>我不太明白你的意思</p>
<blockquote>
<p>Note that option 2 cannot be nested under a header like "Args"</p>
</blockquote>
<p>但实际上,选项2<strong>是</strong>的标准。它提供了记录函数/方法等所需的一切,最重要的是,它的语法是Sphinx文档工具的一部分,任何兼容的解析器都可以正确地、类似地呈现它。例如,考虑如何使用选项2记录这个大类方法(这是一个来自rst文件的copy'n'paste,但是您可以很容易地将其调整为粘贴到docstring中):</p>
<pre><code>.. py:method:: create(**fields)
:module: redmine.managers.ResourceManager
:noindex:
Creates new issue resource with given fields and saves it to the Redmine.
:param project_id: (required). Id or identifier of issue's project.
:type project_id: integer or string
:param string subject: (required). Issue subject.
:param integer tracker_id: (optional). Issue tracker id.
:param string description: (optional). Issue description.
:param integer status_id: (optional). Issue status id.
:param integer priority_id: (optional). Issue priority id.
:param integer category_id: (optional). Issue category id.
:param integer fixed_version_id: (optional). Issue version id.
:param boolean is_private: (optional). Whether issue is private.
:param integer assigned_to_id: (optional). Issue will be assigned to this user id.
:param watcher_user_ids: (optional). User ids who will be watching this issue.
:type watcher_user_ids: list or tuple
:param integer parent_issue_id: (optional). Parent issue id.
:param start_date: (optional). Issue start date.
:type start_date: string or date object
:param due_date: (optional). Issue end date.
:type due_date: string or date object
:param integer estimated_hours: (optional). Issue estimated hours.
:param integer done_ratio: (optional). Issue done ratio.
:param list custom_fields: (optional). Custom fields in the form of [{'id': 1, 'value': 'foo'}].
:param uploads:
.. raw:: html
(optional). Uploads in the form of [{'': ''}, ...], accepted keys are:
- path (required). Absolute path to the file that should be uploaded.
- filename (optional). Name of the file after upload.
- description (optional). Description of the file.
- content_type (optional). Content type of the file.
:type uploads: list or tuple
:return: Issue resource object
</code></pre>
<p>将呈现为:</p>
<p><img src="https://i.stack.imgur.com/WbdYD.png" alt="screenshot"/></p>
<p>我希望您能同意它在原始和呈现形式中产生非常相似和可读的结果。在</p>