在阅读源代码后,运行Sphinx html make时卡住了

2022-04-21 00:00:00 python python-sphinx pycharm

问题描述

我第一次尝试使用Sphinx从我的代码中的文档字符串中获取文档。我目前正在使用pycharm来运行一个狮身人面像任务,但我在命令行上也不太顺利。问题是该进程在不返回任何错误的情况下被触发:

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

任何帮助我们都将不胜感激! 谢谢您


解决方案

已解决。如果在导入时执行,模块中的任何类等待函数都会导致Sphinx在导入时挂起。我使用的是ROS和rosp.Wait_for_service是导致问题的原因。

相关文章