Opened 4 years ago

Closed 4 years ago

#15134 closed (fixed)

modelforms documentation appears twice in doctree

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

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 Changed 4 years ago by Aryeh Leib Taurog <vim@…>

  • Needs documentation unset
  • Needs tests unset
  • Patch needs improvement unset

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

comment:2 Changed 4 years ago by russellm

  • Triage Stage changed from Unreviewed to Ready for checkin

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

comment:3 Changed 4 years ago by russellm

  • Resolution set to fixed
  • Status changed from new to closed

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

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

  • Resolution fixed deleted
  • Status changed from closed to reopened
  • Version changed from 1.2 to SVN

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 Changed 4 years ago by anonymous

  • Resolution set to fixed
  • Status changed from reopened to closed

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 Changed 4 years ago by Aryeh Leib Taurog <vim@…>

  • Resolution fixed deleted
  • Status changed from closed to reopened

You clearly didn't read my last comment.

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

comment:7 Changed 4 years ago by gabrielhurley

  • Resolution set to fixed
  • Status changed from reopened to closed

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