小编Sha*_*tan的帖子

utils我的包装中有一个模块。它由几个不需要实例化的杂项独立方法组成。

我想在此utils文件中放置一些通用注释/文档字符串，例如：

import os
import json

"""
Miscellaneous methods that help in <<blah blah>>
Does not require explicit instantiation.

The following actions can be performed:
===============   ===============
Action            Method
===============   ===============
Get a             :meth:`methoda`
Get b             :meth:`methodb`
"""

def methoda(data):
    "Gets A ..."
    ...

def methodb(data):
    "Gets B ..."
    ...

如上所示，文档字符串具有一个包含指向各个方法的链接的表。目前，我的index.rst这部分内容包括utils：

Utilities
============
.. automodule:: packagename.utils
   :members:

目前，我得到了文档中正确显示的各个方法的文档字符串，但未获取模块的顶级文档字符串（任何类或方法之外）。使狮身人面像包含上述内容的最佳方法是什么？

一种选择是将顶级文档字符串移动到该文件之外，例如，移至index.rstetc。但是我宁愿不这样做，并将其保留在源文件中。

我正在尝试使用sphinx.ext.autosummary来记录 Python 包。由于“自动摘要”要求我们列出要包含的所有项目，因此我想使用 Jinja2 来指定这些项目。

我的conf.py如下（显示相关部分）：

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.autosummary',
    'sphinx.ext.doctest',
    'sphinx.ext.todo',
    'sphinx.ext.coverage',
    'sphinx.ext.viewcode',
    'sphinx.ext.napoleon',
    'sphinx_automodapi.automodapi'
]

autodoc_default_options = {
    'imported-members':True
}
add_module_names = False
autosummary_generate = True
numpydoc_show_class_members = False

def rstjinja(app, docname, source):
    """
    Render our pages as a jinja template for fancy templating goodness.
    """
    # Make sure we're outputting HTML
    if app.builder.format != 'html':
        return
    src = source[0]
    rendered = app.builder.templates.render_string(
        src, app.config.html_context
    )
    source[0] = rendered

def setup(app):
    app.connect("source-read", rstjinja)

# in …

我的数据库结构如下（为了解决这个问题而进行了简化）：

Collection: item_A
    -> Document: params = {someParameter: "value"}
    -> Document: user_01
        -> Sub-collection: orders_item_A
            -> Document: order_AA = {type: "A1", address: {pincode: "000000", city:"Paris"}
            -> Document: order_AB = {type: "A2", address: {pincode: "111111", city:"London"}
            ...
    -> Document: user_02
        -> Sub-collection: orders_item_A
            -> Document: order_AC = {type: "A1", address: {pincode: "222222", city:"Berlin"}
            -> Document: order_AD = {type: "A1", address: {pincode: "333333", city:"Paris"}
            ...

我正在使用集合组查询来检索“item_A”下的所有订单（跨所有用户）。我可以通过以下方式让它发挥作用：

let orders = [];
await firestore()
    .collectionGroup("orders_item_A")
    .get()
    .then(function (querySnapshot) {
        querySnapshot.forEach(function (doc) {
            console.log(doc.id, ' …