1

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

bad_coder
  • 11,289
  • 20
  • 44
  • 72
Mischa
  • 635
  • 6
  • 14

1 Answers1

3

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.

Lukas Graf
  • 30,317
  • 8
  • 77
  • 92
  • Hi Lukas, thank you for your answer. How can I solve the problem? I want absolutly show all tables from a model in the Table of content of each table. Thank yout! – Mischa Aug 28 '12 at 06:07
  • 1
    Unfortunately, I don't think there's a way to solve this problem. I've been in similar situations and haven't found a solution yet - Sphinx simply can't resolve circular toctree references. – Lukas Graf Aug 28 '12 at 20:41