如何使MkDocs侧菜单中的页面可扩展？

Question

我试图寻找这个，但无法得到任何类型的答案，将指向一个解决方案。让我先从一些背景开始，我想。

我的目标是：

我目前正在弄清楚如何为某个python脚本存储库创建一个体面的自动化文档。它是一个库，所以本身不是一个“项目”。它也存在于它自己的地方，因为它不是由独立的python安装维护的，而是由Autodesk Maya附带的Python 2.7实现维护的。因此，库中有一堆模块，按照对我们有意义的方式进行组织，并且所有函数都有一个根据reStructuredText编写的文档字符串（:p aram参数Name：Description等）。我正在寻找一些可以浏览整个存储库的东西，并创建一个漂亮的html文档，看起来整洁，并且可以轻松搜索现有功能，认为它必须存在，但是唉，我无法找到任何用户友好的内容。

我所尝试的：

狮身人面像、pdoc3-都证明了不同程度的不理想性。

我决定要做的是:

我最后一次尝试是mkdocs。这看起来相当简单，不仅因为它实际上不做任何事情，而是创建一个页面的存根，该存根根据用户必须提供的一个.yaml配置文件和每个页面的.md文件进行填充。现在，仅供参考，我对yaml和md都是新手，因为我从未使用过任何一种。我已经决定为自己创建一个包装器（用于一个按钮来实现docs功能），它将基本上运行在我的python库中，为每个模块创建一个.md页面，并用函数/类及其docstring填充它。我必须自己解析文档字符串，但这没什么大不了的。这将基本上将mkdocs变成一个相当不错的自动化文档，无需手动输入。现在…我确实喜欢您可以在yaml配置文件中为文档设置的主题readthedocs，但这就是我遇到的问题。

我的问题

当我'mkdocs服务'我的网站，我希望任何在侧菜单中具有层次结构的东西都是可折叠的，就像在这个例子中一样（注意左侧边栏上的折叠/展开图标）：

但我得到的是不可折叠性:

应该注意的是，我想，在我的例子中,‘attr’部分是一个。md站点，它只有一个简单的结构，每个函数名有一个h3头，在下面有一些描述，然后有一个水平规则来划分下一个函数。

此外，在mydocs结构的yaml配置文件中，结构保持非常简单：

site_name: My Repo
nav:
    - Home: 'index.md'
    - 'Modules':
        - attr: 'pageA.md'
        - pageB: 'pageB.md'
        - pageC: 'pageC.md'
    - About: 'about.md'
theme:
    name: readthedocs
    include_homepage_in_sidebar: false
    highlightjs: true
    hijs_languages:
        - python
markdown_extensions:
    - toc:
        permalink: True
        separator: "_"

所以问题是——我该如何让我的侧边栏有小的展开/折叠图标？(即attr网站在这一点上)这是可行的吗？是否可以通过yaml配置文件或。每页的md文件？

而且，有没有比我做的更好的替代方案，不需要我编写自己的文档制作一键式解决方案？

谢谢你！

Answer 1

也许，你只需要用不同的方式来写。这是它在我的项目中的工作方式：

nav:
  - 'index.md'
  - 'glossary.md'
  - 'Subject1':
    - 'dir/file1.md'
    - 'dir/file2.md'
  - 'Subject2':
    - 'NestedSubject2_1':
      - 'dir/file1.md'
      - 'dir/file2.md'
    - 'NestedSubject2_2':
      - 'dir/file.md'
      - 'dir/file2.md'
      - 'dir/file3.md'
      - 'dir/file4.md'

这是我能展示的至少一点，抱歉。这就是我的项目的结构。