相关疑难解决方法(0)

我正在尝试使用Sphinx来记录Python中的5000多行项目.它有大约7个基本模块.据我所知,为了使用autodoc我需要为我的项目中的每个文件编写这样的代码:

.. automodule:: mods.set.tests
    :members:
    :show-inheritance:

这太繁琐了,因为我有很多文件.如果我能指定我想要记录'mods'包,那将会容易得多.然后,Sphinx可以递归地遍历包并为每个子模块创建一个页面.

有这样的功能吗？如果没有,我可以写一个脚本来制作所有的.rst文件,但这会花费很多时间.

我已经开始使用Sphinx记录Python项目.这是我第一次使用它 - 我习惯使用类似JavaDoc语法的工具,我有些疑惑.

因为我想要的文档出现在代码的旁边,我利用的.. automodule::,.. autoclass::和.. automethod::指令.所以我的文档结构如下:index.rst包含TOC和

.. automodule:: my_main_package

然后顶级__init__.py包含指令

.. automodule:: some_subpackage

对于每个子包等等.最后,每个模块都包含指令

.. autoclass:: some_class
    :members:

对于模块中的每个类.

这主要是有效的,但我得到的是单页文档,这有点奇怪.

我应该如何组织文档以获取超链接文件树？也就是说,主程序包应该包含自己的文档和每个子包的链接,依此类推,直到每个模块都有自己的页面.

我想通过reST生成文档,但不想手动编写reST源代码,而是让python脚本执行该操作,然后使用sphinx生成其他格式(HTML,PDF).

想象一下,我有一个二进制格式的电话簿.现在我使用python脚本来解析它并生成一个包含所有名称和数字的文档:

  phone_book = PhonebookParser("somefile.bin")

  restdoc = restProducer.NewDocument()
  for entry in phone_book:
    restdoc.add_section( title = entry.name, body = entry.number )

  restdoc.write_to_file("phonebook.rst")

然后我会继续调用sphinx来生成pdf和html:

  > sphinx phonebook.rst -o phonebook.pdf
  > sphinx phonebook.rst -o phonebook.html

是否有一个python模块(在上面的例子中也称为restProducer)提供了一个用于生成reST的API？或者是通过几个打印语句转储reST标记的最佳方法？

所以我将python源文件放在两个不同的目录中: -

例如

~/work/myproject
~/.virtualenvs/myproject

如何使用sphinx-apidoc递归查看两个目录来生成我的reST文件？

明显,

sphinx-apidoc -o docs/source ~/work/myproject

工作完全正常,但当我试图跑

sphinx-apidoc -o docs/source ~/.virtualenvs/myproject

再一次,sphinx告诉我"docs/source/modules.rst已经存在,跳过"当然这是真的,因为我已经运行sphinx-apidoc过一次来生成它.

那么如何执行一次并在两个目录中搜索？

我有一个具有以下结构的项目（我想保留）：

my_project\n\xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80 build  # here is where sphinx should dump into\n\xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80 requirements.txt\n\xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80 make.bat\n\xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80 Makefile\n\xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80 ...  # more config files\n\xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80 doc  # this is where I want sphinx files to live\n\xe2\x94\x82\xc2\xa0\xc2\xa0 \xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80 conf.py\n\xe2\x94\x82\xc2\xa0\xc2\xa0 \xe2\x94\x94\xe2\x94\x80\xe2\x94\x80 index.rst\n\xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80 src\n\xe2\x94\x82\xc2\xa0\xc2\xa0 \xe2\x94\x94\xe2\x94\x80\xe2\x94\x80 my_project\n\xe2\x94\x82       \xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80 __init__.py\n\xe2\x94\x82\xc2\xa0\xc2\xa0     \xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80 module_1\n\xe2\x94\x82\xc2\xa0\xc2\xa0     \xe2\x94\x82   \xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80 __init__.py\n\xe2\x94\x82\xc2\xa0\xc2\xa0     \xe2\x94\x82   \xe2\x94\x94\xe2\x94\x80\xe2\x94\x80 ...\n\xe2\x94\x82\xc2\xa0\xc2\xa0     \xe2\x94\x94\xe2\x94\x80\xe2\x94\x80 util\n\xe2\x94\x82\xc2\xa0\xc2\xa0         \xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80 __init__.py\n\xe2\x94\x82\xc2\xa0\xc2\xa0         \xe2\x94\x94\xe2\x94\x80\xe2\x94\x80 ...\n\xe2\x94\x94\xe2\x94\x80\xe2\x94\x80 tests\n    \xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80 module_1\n    \xe2\x94\x82   \xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80 __init__.py\n    \xe2\x94\x82   \xe2\x94\x94\xe2\x94\x80\xe2\x94\x80 ...  # testing module 1\n    \xe2\x94\x94\xe2\x94\x80\xe2\x94\x80 util\n        \xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80 __init__.py\n        \xe2\x94\x94\xe2\x94\x80\xe2\x94\x80 ...  # testing util stuff\n

我在github上 …