从文档字符串生成 sphinx 文档不起作用

Question

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

\n\n

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

\n\n

我在github上重新创建了它，可以通过执行来重新创建结果my_setup.sh在其中执行来重新创建结果。

\n\n

我想从文档字符串构建文档。我使用 sphinx 的快速入门来生成必要的配置，但是当我调用 时make hmtl，生成的文档不包含我的源代码中的任何文档字符串，即my_project/src/my_project. 鉴于我觉得我正在尝试建立一些非常基本的东西，Sphinx 的文档有点让人不知所措。

\n\n

配置文件中的相关信息（如果我忘记了一些重要的信息，请告诉我）：

\n\n

生成文件

\n\n

SPHINXOPTS    =\nSPHINXBUILD   = sphinx-build\nSPHINXPROJ    = my_project\nSOURCEDIR     = doc\nBUILDDIR      = build\n...\n

\n\n

制作.bat

\n\n

set SOURCEDIR=doc\nset BUILDDIR=build\nset SPHINXPROJ=my_project\n...\n

\n\n

.conf.py

\n\n

import os\nimport sys\nsys.path.insert(0, os.path.abspath(\'../src/my_project\'))\n...\nextensions = [\n    \'sphinx.ext.autodoc\',\n    \'sphinx.ext.todo\',\n    \'sphinx.ext.coverage\',\n]\n...\n

\n\n

---

\n\n

我也尝试过这个，但它首先将一堆构建文件放入doc我不想在那里的文件中，并且它也没有找到任何模块（通过省略参数来修复-F）：

\n\n

$ sphinx-apidoc -F -o doc/ src/my_project/\n$ cd doc\n$ make html\nRunning Sphinx v1.7.2\nloading pickled environment... done\nbuilding [mo]: targets for 0 po files that are out of date\nbuilding [html]: targets for 0 source files that are out of date\nupdating environment: 0 added, 2 changed, 0 removed\nreading sources... [100%] my_project.util                                                                                                                                                                                  \nWARNING: autodoc: failed to import module \'my_project\'; the following exception was raised:\nNo module named \'my_project\'\nWARNING: autodoc: failed to import module \'my_project.util.test_file\'; the following exception was raised:\nNo module named \'my_project\'\nWARNING: autodoc: failed to import module \'my_project.util\'; the following exception was raised:\nNo module named \'my_project\'\nlooking for now-outdated files... none found\npickling environment... done\nchecking consistency... /home/arne/workspace/git/my_project/doc/my_project.rst: WARNING: document isn\\\'t included in any toctree\ndone\npreparing documents... done\nwriting output... [100%] my_project.util                                                                                                                                                                                   \ngenerating indices... genindex\nwriting additional pages... search\ncopying static files... done\ncopying extra files... done\ndumping search index in English (code: en) ... done\ndumping object inventory... done\nbuild succeeded, 4 warnings.\n

\n

Answer 1

您的 MCVE 有几个问题。

1. rST 源文件不得驻留在输出目录中build，而应位于 docs 源目录中docs。你应该这样做sphinx-apidoc -o docs src/my_project：

2. 正如 @mzjn 提到的，您需要取消注释并添加一些行conf.py来解决WARNING: autodoc: failed to import module错误。

   # -- Path setup --------------------------------------------------------------
   
   # If extensions (or modules to document with autodoc) are in another directory,
   # add these directories to sys.path here. If the directory is relative to the
   # documentation root, use os.path.abspath to make it absolute, like shown here.
   #
   import os
   import sys
   # sys.path.insert(0, os.path.abspath('.'))
   sys.path.insert(0, os.path.abspath('../src/'))
   

经过这两项更改后，我能够使用其 API 成功构建您的文档。