Opened 13 years ago

Closed 13 years ago

#15134 closed (fixed)

modelforms documentation appears twice in doctree

Reported by: Aryeh Leib Taurog <vim@…> Owned by: nobody
Component: Documentation Version: dev
Severity: Keywords:
Cc: vim@… Triage Stage: Ready for checkin
Has patch: no Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no

Description

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

Change History (7)

comment:1 by Aryeh Leib Taurog <vim@…>, 13 years ago

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

comment:2 by Russell Keith-Magee, 13 years ago

Triage Stage: UnreviewedReady for checkin

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

comment:3 by Russell Keith-Magee, 13 years ago

Resolution: fixed
Status: newclosed

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

comment:4 by Aryeh Leib Taurog <vim@…>, 13 years ago

Resolution: fixed
Status: closedreopened
Version: 1.2SVN

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.

comment:5 by anonymous, 13 years ago

Resolution: fixed
Status: reopenedclosed

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.

comment:6 by Aryeh Leib Taurog <vim@…>, 13 years ago

Resolution: fixed
Status: closedreopened

You clearly didn't read my last comment.

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

comment:7 by Gabriel Hurley, 13 years ago

Resolution: fixed
Status: reopenedclosed

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.

Note: See TracTickets for help on using tickets.
Back to Top