Question

我正在关注一个针对python项目的Sphinx教程，似乎无法获取自动创建的HTML文件来放入函数doc-strings。

我按照入门网站Sphinx Getting Started Guide上的说明进行操作，并成功创建了具有基本知识的HTML（大部分为空）。

这是我的测试项目的结构：

- /sphinx-test/
  -- doc/
  -- sphinx-test/
    --- __init__.py
    --- api.py

__init__.py为空，并且api.py中具有一个功能：

def square_num(num):
    """Example function
    Args:
        num (float): A float to square.

    Returns:
        float: The squared number
    """
    return num**2

我导航到doc/目录并运行$sphinx-quickstart。

这是我回答$sphinx-quickstart问题的方式：

> Root path for the documentation [.]: 
> Separate source and build directories (y/n) [n]: y
> Name prefix for templates and static dir [_]: 
> Project name: sphinx_test
> Author name(s): nick
> Project version: 0.0.1
> Project release [0.0.1]: 
> Project language [en]: 
> Source file suffix [.rst]: 
> Name of your master document (without suffix) [index]: 
> Do you want to use the epub builder (y/n) [n]: 
> autodoc: automatically insert docstrings from modules (y/n) [n]: y
> doctest: automatically test code snippets in doctest blocks (y/n) [n]: y
> intersphinx: link between Sphinx documentation of different projects (y/n) [n]: n
> todo: write "todo" entries that can be shown or hidden on build (y/n) [n]: y
> coverage: checks for documentation coverage (y/n) [n]: y
> imgmath: include math, rendered as PNG or SVG images (y/n) [n]: n
> mathjax: include math, rendered in the browser by MathJax (y/n) [n]: n
> ifconfig: conditional inclusion of content based on config values (y/n) [n]: y
> viewcode: include links to the source code of documented Python objects (y/n) [n]: y
> githubpages: create .nojekyll file to publish the document on GitHub pages (y/n) [n]: n
> Create Makefile? (y/n) [y]: y
> Create Windows command file? (y/n) [y]: n

我在conf.py构建文件中进行了一项更改，以便Sphinx可以将一个目录向上导航到项目。这是conf.py中的相关行：

# -*- coding: utf-8 -*-
import os
import sys
sys.path.insert(0, os.path.abspath('../'))
extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.doctest',
    'sphinx.ext.todo',
    'sphinx.ext.coverage',
    'sphinx.ext.viewcode',
]
templates_path = ['_templates']
source_suffix = '.rst'
master_doc = 'index'
project = u'sphinx_test'
copyright = u'2019, foobar'
author = u'foobar'
version = u'0.0.1'
release = u'0.0.1'
language = None
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
pygments_style = 'sphinx'
todo_include_todos = True
html_theme = 'alabaster'
html_static_path = ['_static']
htmlhelp_basename = 'sphinx_testdoc'

latex_elements = {
}

latex_documents = [
    (master_doc, 'sphinx_test.tex', u'sphinx\\_test Documentation',
     u'foobar', 'manual'),
]

man_pages = [
    (master_doc, 'sphinx_test', u'sphinx_test Documentation',
     [author], 1)
]

texinfo_documents = [
    (master_doc, 'sphinx_test', u'sphinx_test Documentation',
     author, 'sphinx_test', 'One line description of project.',
     'Miscellaneous'),
]

然后我跑了$make html。

这按预期生成了一个index.html文件，但是它不包含我的square_num()文档字符串上的任何信息。我还没有编辑任何其他sphinx-quickstart默认文件。

我应该怎么做才能获得文档中的文档字符串？

编辑：

这与不是完全相同 How to generate Python documentation using Sphinx with zero configuration?

该问题中的特定解决方案不起作用。在conf.py的第3行中，我已经通过添加以下行实现了该解决方案：sys.path.insert(0, os.path.abspath('../'))。尽管问题是相同的，但解决方案却略有不同。

我找到的解决方案是在那行之后： sys.path.append(os.path.join(os.path.dirname(__name__), '..'))（请参阅答案）

Answer 1

经过大量的跟踪和错误处理后，我发现按如下方式编辑conf.py文件是可行的：

import os
import sys
sys.path.insert(0, os.path.abspath('../'))
sys.path.append(os.path.join(os.path.dirname(__name__), '..'))

Sphinx项目自动文档

1 个答案: