“preparing documents” hangs - toctree circular references in Sphinx

Question

i try to generate a documentation with Sphinx but the generation hangs on "preparing documents .." I search for a solution but I don't find any advice to solve the problem.

The problem appears after adding a Table of content to all files. The structure of the documentation looks like this :

a few Models: Every model has some Tables ( one file per table) example:

• Model = AUDITRAIL
• Tables = AUDITTRAIL_BFLOG.rst, AUDITTRAIL_SESSIONLOG.rst

AUDITRAIL.rst

AUDITTRAIL
==========

.. toctree::
   :maxdepth: 1

   AUDITTRAIL_BFLOG.rst
   AUDITTRAIL_SESSIONLOG.rst

AUDITTRAIL_SESSIONLOG.rst

AUDITTRAIL.SESSIONLOG

.. toctree:: :maxdepth: 1

AUDITTRAIL.rst

Keys and indexes

===== ===== ==================== seq type fields
===== ===== ==================== 1 P SESSIONLOGID 2 I USRID,SESSIONLOGID ===== ===== ====================

Fields

===== ==================== ===== ===== ========== =============== ==================== seq fieldname type inDB interface widgettype description
===== ==================== ===== ===== ========== =============== ==================== 5 CLIENTNAME S Y W20 EDITBOX Client name 4 COMPUTERNAME S
Y W20 EDITBOX Server name 6
CREDATIM E Y E8 EDITBOX Creation date field 11 DESCR S Y W1024
EDITBOXLONG Description field 10 LABEL S
Y W100 EDITBOX Label field 1
SESSIONLOGID N Y C10 EDITBOX Id field 8 UPDDATIM E Y E8
EDITBOX Update date field 2 USRID N
Y C10 EDITBOX id user 7
USRIDCRE N Y C10 EDITBOX Creation user id field 9 USRIDUPD N Y C10
EDITBOX Update user id field *3 USR_CODE S
N W30 EDITBOX * ===== ==================== ===== ===== ========== =============== ====================

I added a table of content on every table file to reference to the other tables from the same model. I hope somebody can help me.

Greeting, Mischa

Answer 1

You've got circular references in your documents' TOCs.

AUDITRAIL.rst references AUDITTRAIL_SESSIONLOG.rst in its TOC, and AUDITTRAIL_SESSIONLOG.rst references back to AUDITTRAIL.rst. You can't have circular toctree references, you need to remove the .. toctree:: directive from one file or the other.

Up until 1.1.3 Sphinx failed with a RuntimeError: maximum recursion depth exceeded in cmp, in 1.1.3 this was changed to ignoring the circular toctree references and printing a warning message.