Issue #1545 wontfix

:orphan: options sometimes shows up

Pierre-Antoine Champin
created an issue

More precisely, I use the :orphan: option in RST files that are not used in the toctree, but are included by other files (for factorizing role declarations, for example).

If the include directive is at the top of the including file, then no problem, the :orphan: does not appear, as expected. However, if the include directives appears at other places, then the :orphan: option shows up at the beginning of the included content.

Although I guess I understand why this happens, it seems to contradict the documentation stating that:

In Sphinx, a field list preceding any other markup (...) is not displayed in the output.

Also, this is in my opinion a bug worth fixing, as included files are an obvious use case for the :orphan: option.

Comments (3)

  1. Takayuki Shimizukawa

    It might be a docutils specification (or limitation), not a bug.

    docinfo reST syntax is a same as field-list. When a field-list placed at the top of the file, it will become docinfo.

    BTW, include directive include another file into the caller document. In this case, these 2 files are interpreted into 1 doctree intermediate structure. At this time, :orphan: is not docinfo anymore.

  2. Log in to comment