问题描述
我正在尝试使用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文件生成文档。但是，我所有的尝试都导致文档空白，我想我误会了一些东西。
我试图按照官方的快速入门指南：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'不存在”不重要。
我想念什么？
解决方法
听起来好像您没有定义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