Question

我第一次尝试使用Sphinx从我的代码中获取docstrings的文档。我目前正在使用pycharm来运行sphinx任务，但我也没有运行命令行。问题是进程被触发而没有返回任何错误：

Running Sphinx v1.2.2
loading pickled environment... done
building [html]: targets for 1 source files that are out of date
updating environment: 0 added, 1 changed, 0 removed
reading sources... [100%] index

然后什么也没有。

我尝试按照Sphinx文档和在线提供的指南，但也许我弄错了。这些是我的index.rst文件：

Welcome to Mycode's documentation!
===================================

Contents:

.. automodule:: mycode
   :members:

___________________________________

**Sub-Modules:  **

.. toctree::
   :maxdepth: 2

   mycode.TerminalColors


Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

这是我的conf.py：

sys.path.insert(0, os.path.abspath('..'))
sys.path.insert(0, os.path.abspath('../docs'))
sys.path.insert(0, os.path.abspath('../scripts'))
sys.path.insert(0, os.path.abspath('../source'))
print(sys.path)

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.viewcode',
    'sphinxcontrib.napoleon'
]

# Napoleon settings
napoleon_google_docstring = True
napoleon_numpy_docstring = True
napoleon_include_private_with_doc = False
napoleon_include_special_with_doc = True
napoleon_use_admonition_for_examples = False
napoleon_use_admonition_for_notes = False
napoleon_use_admonition_for_references = False
napoleon_use_ivar = False
napoleon_use_param = True
napoleon_use_rtype = True

autodoc_member_order = 'groupwise'

templates_path = ['.templates']

source_suffix = '.rst'

master_doc = 'index'

project = u'Mycode'
copyright = u'2016, Me'
version = '1.0'
release = '1.0'
exclude_patterns = []
pygments_style = 'sphinx'

html_theme = 'default'
html_static_path = ['.static']
htmlhelp_basename = 'Mycodedoc'

latex_elements = {}
latex_documents = [
  ('index', 'Mycode.tex', u'Mycode Documentation',
   u'me', 'manual'),
]

man_pages = [
    ('index', 'mycode', u'mycode Documentation',
     [u'me'], 1)
]

texinfo_documents = [
  ('index', 'Mycode', u'Mycode Documentation',
   u'me', 'Mycode', 'One line description of project.',
   'Miscellaneous'),
]

最后，这是我的项目结构：

-mycode
   -scripts
      -mycode.py
   -docs(output folder)
      -index.html
      -...
   -build
   -source
       -conf.py
       -index.rst

任何帮助将非常感谢！谢谢

Answer 1

解决。模块中的任何 等待函数 似乎会导致Sphinx在导入时挂起，如果它在导入时执行的话。我使用ROS并且 rospy.wait_for_service 导致了这个问题。

在阅读消息来源后，运行Sphinx html make会卡住

1 个答案: