由于缺少标题（在索引中），无法构建 link 文档

Question

我正在使用 sphinx 作为文档。当我使用“make confluence”时，我从 index.rst 文件中收到以下警告。

如何删除这些警告？此外，由于这些警告，Table 的内容无法正常工作，但正在代码中创建文档。

任何 suggestion/help 都将受到高度赞赏。

[4px@learning-2 docs]$ make confluence
Running Sphinx v4.2.0
loading pickled environment... done
building [mo]: targets for 0 po files that are out of date
building [confluence]: targets for 0 source files that are out of date
updating environment: 0 added, 1 changed, 0 removed
/usr/lib64/python3.6/importlib/_bootstrap.py:219: RuntimeWarning: numpy.ufunc size changed, may indicate binary incompatibility. Expected 192 from C header, got 216 from PyObject
  return f(*args, **kwds)
/usr/lib64/python3.6/importlib/_bootstrap.py:219: RuntimeWarning: numpy.ufunc size changed, may indicate binary incompatibility. Expected 192 from C header, got 216 from PyObject
  return f(*args, **kwds)
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index
/home/4px/sphinx/docs/source/index.rst:: WARNING: unable to build link to document due to missing title (in index): genindex
/home/4px/sphinx/docs/source/index.rst:: WARNING: unable to build link to document due to missing title (in index): py-modindex
/home/4px/sphinx/docs/source/index.rst:: WARNING: unable to build link to document due to missing title (in index): search
publishing documents... [100%] index
Publish point: https://<........>.atlassian.net/wiki/spaces/DOCS/pages/4194009282
building intersphinx... done

build succeeded, 3 warnings.

index.rst 文件-

.. 4px documentation master file, created by
   sphinx-quickstart on Tue Oct 26 11:19:49 2021.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

API Documentation
**************************

CODE DOCUMENTATION
====================================

.. toctree::
      :hidden:

   index



featureSelection
==================
.. automodule:: featureSelection
   :members:


interpolate
============
.. automodule:: interpolate
      :members:

pets
============
.. automodule:: pets
         :members:


Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

我遇到了一个关于此警告的 github 问题，但它是针对旧版本的。

Sphinx 2.2.2 warning · Issue #265 · sphinx-contrib/confluencebuilder

Answer 1

我不确定这是否有帮助，但您的 reStructuredText 具有随机缩进和不匹配的标题下划线长度。 White space 在 reStructuredText 中很重要。尝试清理它，像这样：

API Documentation
*****************

CODE DOCUMENTATION
==================

.. toctree::
    :hidden:

    index


featureSelection
================
.. automodule:: featureSelection
    :members:


interpolate
===========
.. automodule:: interpolate
    :members:


pets
====
.. automodule:: pets
    :members:


Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

Answer 2

清理 index.rst 文件并为每个 python 脚本创建单独的第一个文件后，将删除以下警告，而不是像上面那样在 index.rst 中添加结构化格式。

在 confluence 中自行创建 TOC 页面还有一个好处。

index.rst的结构应该在cd docs/sources目录下面，其中assets,plant,Site,pipeline是python脚本的名字

index.rst-

.. spectRRa documentation master file, created by
   sphinx-quickstart on Fri Apr 24 11:55:57 2020.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

**API Docs**
***************
.. toctree::
   assets
   plants
   pipelines
   sites

同时在 cd docs/sources/ 目录中创建所有单独的第一个文件。

Ex-对于assets.py脚本，assets.rst文件将在下方。

assets.rst-

.. spectRRa documentation master file, created by
 sphinx-quickstart on Fri Apr 24 11:55:57 2020.
 You can adapt this file completely to your liking, but it should at least
 contain the root `toctree` directive.

 .. toctree::
       :maxdepth: 2
       :caption: Contents:

**Assets**
=================

.. automodule:: assets
    :members:

注意-请不要更改缩进，否则它将不起作用并抛出缩进警告。

参考 Link-

Sphinx Documentation

由于缺少标题（在索引中），无法构建 link 文档

Unable to build link to document due to missing title (in index)

python-sphinx

restructuredtext

confluence