Sphinx 没有找到任何来源

Question

我正在尝试使用 sphinx 为我项目的 python 部分生成文档。我想在 gitlab-ci 文件中做，但现在我什至不能让它在本地工作。

项目结构：

dev/
 src/
   other-src/
   python-api/
      src/
         conf.py
         index.rst
         mymodule/
           submodule1/
             some python files
           submodule2/
             some python files
           submodule3/
             some python files
           some python files
doc/
  source/
  build/
public/

我想为 dev/src/python/src/mymodule 中的所有 python 个文件生成文档。然而，我所有的尝试都导致了一个空文档，我想我误解了什么。

我尝试按照官方cial 快速入门：https://www.sphinx-doc.org/en/master/usage/quickstart.html

user@host:~/test$ cd doc/
user@host:~/test/doc$ sphinx-quickstart 
Bienvenue dans le kit de démarrage rapide de Sphinx 3.2.1.

Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).

Selected root path: .

You have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.
> Séparer les répertoires build et source (y/n) [n]: y

The project name will occur in several places in the built documentation.
> Nom du projet: *******
> Nom(s) de l'auteur: *********
> version du projet []: ***

If the documents are to be written in a language other than English,
you can select a language here by its language code. Sphinx will then
translate text that it generates into that language.

For a list of supported codes, see
https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language.
> Langue du projet [en]: en

Fichier en cours de création /test/doc/source/conf.py.
Fichier en cours de création /test/doc/source/index.rst.
Fichier en cours de création /test/doc/Makefile.
Fichier en cours de création /test/doc/make.bat.

Terminé : la structure initiale a été créée.

You should now populate your master file /test/doc/source/index.rst and create other documentation
source files. Use the Makefile to build the docs, like so:
   make builder
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.
user@host:~/test/doc$

作为这一步，如果我按照建议使用“make html”，则会生成一个空文档。所以我继续指南：

user@host:~/test/doc$ cd source/
user@host:~/test/doc/source$ cp index.rst ../dev/src/python-api/src/
user@host:~/test/doc/source$ cp conf.py ../dev/src/python-api/src/
user@host:~/test/doc/source$ sphynx-build -b html ../../dev/src/python-api
sphinx-build -b html ../../dev/src/python-api/src/ ../build
Sphinx v3.2.1 en cours d'exécution
WARNING: l'entrée html_static_path '_static' n'existe pas
construction en cours [mo]:cibles pour les fichiers po 0 qui sont périmées
construction [html]:cibles pour les fichiers sources 1 qui sont périmées
mise-à-jour de l'environnement :[nouvelle configuration] 1 ajouté, 0 modifié, 0 supprimé
lecture des sources... [100%] index                                                           
recherche des fichiers périmés... aucun résultat
environnement de sérialisation... fait
vérification de la cohérence... fait
document en préparation... fait
écriture... [100%] index                                                                      
generating indices...  genindexfait
writing additional pages...  searchfait
copie des fichiers statiques... ... fait
copying extra files... fait
dumping search index in English (code: en)... fait
dumping object inventory... fait
la compilation a réussi, 1 avertissement.

Les pages HTML sont dans ../build .

同样，文档 html 不包含任何代码。我想警告“警告：条目 html_static_path '_static' 不存在”并不重要。

我错过了什么？

Answer 1

听起来您没有定义文档字符串中文档的哪些部分应该被 Sphinx 考虑。例如，假定您有一个文件 ./docs/sourc/index.rst，其中包含如下内容：

.. automodule:: python.package.path.to.class
    :noindex:

实际上有很多不同的可能性来构建您的文档： https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html

完成后，只需进入您的 doc 文件夹并执行以下命令：

sphinx-build -b html source build

Sphinx 没有找到任何来源

Sphinx does not find any source

python

python-sphinx