python - GitHub sphinx-action 找不到目标 Python 模块并构建一个空的 sphinx doc

Question

Tl;博士

当我在本地创建一个 sphinx 文档时，它会按预期构建，但GitHub Sphinx 构建操作会创建一个空文档。它必须与 sphinx-action 没有找到 中指定的目标 python 模块有关conf.py。

配置狮身人面像动作或conf.py正确的任何想法？

预期的狮身人面像文档

当我通过生成的 html 在我的机器上本地构建 sphinx 文档时，cd docs/ && make html看起来符合预期

sphinx-action 生成的空 Sphinx Doc

我的.github/workflows/sphinx_action.yml包括

    steps:
    # Checkout repo
    - uses: actions/checkout@v2
    # Build sphinx doc
    - uses: ammaraskar/sphinx-action@master
      with:
        docs-folder: "docs/"

并生成一个 Sphinx Doc 的空骨架

项目设置

项目结构

.
├── docs
│   ├── conf.py
│   ├── index.rst
│   ├── make.bat
│   ├── Makefile
│   ├── requirements.txt
│   └── sync.log
├── .github
│   └── workflows
│       └── sphinx_action.yml
├── .gitignore
├── mypackage
│   ├── __init__.py
│   ├── subfolder
│   │   ├── __init__.py
│   │   └── subclass.py
│   └── superclass.py
├── Pipfile
├── Pipfile.lock
└── README.md

conf.py配置

我的docs/conf.py样子如下。（请注意，sys.path为了让 Sphinx 找到所有 python 模块，我手动添加了三个条目。）

# Configuration file for the Sphinx documentation builder.
#
# This file only contains a selection of the most common options. For a full
# list see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html


# -- 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
from m2r import MdInclude

sys.path.insert(0, os.path.abspath('..'))
sys.path.insert(0, os.path.abspath('../mypackage'))
sys.path.insert(0, os.path.abspath('../mypackage/subfolder'))


# -- Project information -----------------------------------------------------

project = 'MyPackage'
copyright = ''
author = 'Testuser'


# -- General configuration ---------------------------------------------------

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = ['sphinx.ext.autodoc',
              'recommonmark'
]

# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']

#
source_suffix = ['.rst', '.md']

# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']

# document the init of a class, too
autoclass_content = 'both'

# -- Options for HTML output -------------------------------------------------

# The theme to use for HTML and HTML Help pages.  See the documentation for
# a list of builtin themes.
#
html_theme = 'nature'

# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']

# from m2r to make `mdinclude` work
def setup(app):
    config = {
        # 'url_resolver': lambda url: github_doc_root + url,
        'auto_toc_tree_section': 'Contents',
        'enable_eval_rst': True,
    }

    # from m2r to make `mdinclude` work
    app.add_config_value('no_underscore_emphasis', False, 'env')
    app.add_config_value('m2r_parse_relative_links', False, 'env')
    app.add_config_value('m2r_anonymous_references', False, 'env')
    app.add_config_value('m2r_disable_inline_math', False, 'env')
    app.add_directive('mdinclude', MdInclude)

点文件

[[source]]
verify_ssl = true
url = "https://pypi.org/simple"
name = "pypi"

[dev-packages]

[packages]
m2r = {index = "pypi",version = "==0.2.1"}
pandas = {index = "pypi",version = "==1.0.3"}
sphinx = {index = "pypi",version = "==3.1.0"}
recommonmark = {index = "pypi",version = "==0.6.0"}
mypackage = "*"

[requires]
python_version = "3.8"

注意：我也将此问题作为问题发布在 sphinx-action 的 GitHub 存储库中。

标签： pythonpython-3.xpython-sphinxgithub-actionsautodoc

Answer 1

我有完全相同的问题。简单地说

import mypackage

为conf.py我固定的东西。

编辑： mypackage上面指的是实际的包名称，并且会具体。为了使其工作，您需要确保实际安装了包（例如使用setuptools）。以下是 GitHub 操作的代码片段

    - uses: ammaraskar/sphinx-action@master
      with:
        #pre-build-command: "apt-get update -y && apt-get install -y pandoc"
        docs-folder: "docs/"

和我的requirements.txt文件（在docs）

sphinx>=3.3
sphinx-autodoc-typehints
sphinx-argparse
-e .

我留下了注释掉，pre-build-command因为你也可以使用它pip install -e .。我不认为狮身人面像版本很重要。