modelforms documentation appears twice in doctree

[Aryeh Leib Taurog <vim@…>]

docs/topics/forms/modelforms.txt is included in the toctree from two locations:

• docs/topics/index.txt
• docs/topics/forms/index.txt

This is confusing for the reader.

I suggest that the toctree entry in topics/index be retained and the toctree entry in topics/forms/index be removed or converted to a regular cross-reference link. The reasons I would prefer that are:

1. ModelForms is sufficiently large, complex, and important a topic to warrant it's own section
2. It will be easier to find in the docs if it has a 2nd-level heading
3. It doesn't make sense to introduce ModelFormsets before introducing Formsets

[Aryeh Leib Taurog <vim@…>]

N.B. I checked for other cases of duplication in the docs and didn't find any

[Russell Keith-Magee]

Marking RFC because the fix is a trivial 1 line deletion.

[Russell Keith-Magee]

(In [15366]) Fixed #15134 -- Removed a duplicate TOC entry for modelforms docs. Thanks to Aryeh Leib Taurog for the report.

[Aryeh Leib Taurog <vim@…>]

I envisioned keeping the other TOC entry, as I detailed above. However, if you're to keep the TOC entry here--and I admit this is more naturally implied by the file's location in the source tree--I suggest it be put after the TOC entry for FormSets. The reason for this is that an understanding of FormSets is a prerequisite for understanding ModelFormSets and InlineModelFormsets, which are discussed in the ModelForms section.

[anonymous]

In this instance, I think Russ' fix was appropriate. The entry in the Topics index didn't belong there, its proper home is in the Forms index.

While I agree that ModelForms and ModelFormsets are important, they are accessible from both the Forms index *and* from the front page of the docs ("forms for models"). I think this is sufficient for arriving at the correct location.

To the point of "I suggest that [...] the toctree entry in topics/forms/index be [...] converted to a regular cross-reference link": That link is using Sphinx's auto-generated TOC mechanism, which creates a normal cross-reference. It just so happens that the second-level heading in that document is also marked as an inline code block (which is perfectly fine). That markup carries across to the TOC, hence the different appearance.

I'm gonna re-close this as fixed, but thank you for your input Aryeh.

[Aryeh Leib Taurog <vim@…>]

You clearly didn't read my last comment.

This only about the order of the TOC entries in topics/forms/index

[Gabriel Hurley]

In [15447]:

Fixed #15134 -- Placed formset documentation before modelform documentation in the forms topic index to improve the logical flow of information being presented. Thanks to Aryeh Leib Taurog for the report.