Opened 11 years ago

Closed 11 years ago

Last modified 11 years ago

#20830 closed Bug (fixed)

Bad URL for six.moves in "Porting to Python 3 / Moved modules"

Reported by: German Larrain Owned by: Daley Chetwynd
Component: Documentation Version: dev
Severity: Normal Keywords: six, python3, afraid-to-commit
Cc: timograham@…, Daniele Procida Triage Stage: Accepted
Has patch: no Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: yes UI/UX: no

Description (last modified by Daniele Procida)

The renderized URL is http://pythonhosted.org/six/index.html#six.moves and should be http://pythonhosted.org/six/index.html#module-six.moves

I traced the error to lines 368 and 371 in the rst source file but my knowledge of reStructuredText is very limited.

Also, it seems weird to have a hyperlink with value "django.utils.six.moves" pointing to the actual "six" documentation since Django includes a custom version of it, albeit very similar. Perhaps it will be clearer to have something like "six.moves <six.moves>".

Marked as easy-pickings for the second issue. I'm not sure what's going on with the first.

Change History (12)

comment:1 by Tim Graham, 11 years ago

Cc: timograham@… added
Easy pickings: unset
Summary: Bad URL in "Porting to Python 3 / Moved modules"Bad URL for six.moves in "Porting to Python 3 / Moved modules"
Triage Stage: UnreviewedAccepted

I think this may be a sphinx, intersphinx, or six docs issue, but I haven't taken a deep dive to determine the root cause. As you described above, the six docs ID that's generated is "module-six.moves" instead of the expected "six.moves".

comment:2 by Daniele Procida, 11 years ago

Cc: Daniele Procida added
Description: modified (diff)
Easy pickings: set
Keywords: afraid-to-commit added

Sphinx on my local installation also renders the links to http://pythonhosted.org/six/index.html#module-six.moves and http://pythonhosted.org/six/index.html#module-six incorrectly, failing to include the module- part.

There's still the second issue, which we can do something about, where our docs say:

Some modules were renamed in Python 3. The :mod:`django.utils.six.moves
<six.moves>` module provides a compatible location to import them.

In other words, we are referring to a Python module (<six.moves>), but the hyperlink text (django.utils.six.moves) appears to refer to something in Django, so that hyperlink text should be changed. We could say something like:

The Python :mod:`six.moves <six.moves>` module... 

comment:3 by Tim Graham, 11 years ago

Django includes a copy of six, hence the django.utils.six.moves reference. In the context of the sentence, it makes sense to reference this location.

comment:4 by Daley Chetwynd, 11 years ago

Owner: changed from nobody to Daley Chetwynd
Status: newassigned

I am fixing this bug as part of the Django development sprint at PyCon UK 2013.

comment:5 by Daley Chetwynd, 11 years ago

I've just rendered this page myself with Sphinx using Firefox 23.0.1 and Sphinx version 1.2b2 on Fedora 19. The link in question does render correctly in my browser as http://pythonhosted.org/six/index.html#module-six.moves, so the "module-" prefix of the link anchor is not omitted, unlike on EvilDMP's system. This may therefore only be an issue with some versions of Sphinx.

comment:6 by Daley Chetwynd, 11 years ago

In relation to the second issue on links to the six module, there are inconsistencies between links to the Python version of six and links to the Django version of six. In the /topics/python3.html documentation page are seven links to the six module. Four of these links are correct, but the following three links are to the Python version of six, instead of the Django version:

1) The "six" link in the third sentence of the "Writing compatible code with six" section
2) The "django.utils.six.moves" link in the second sentence of the "Moved modules" section
3) The "six" link in the final sentence of the "PY2" section

I will therefore change these three links to the correct targets.

Last edited 11 years ago by Daley Chetwynd (previous) (diff)

comment:7 by Daniele Procida, 11 years ago

I don't think it's necessarily incorrect to link to the Python version of the docs, but it is certainly confusing to link to them with link text that suggests we're speaking of Django docs. So I think it's worth noting that documentation for (nearly all you need to know about) Django's version (rather than 'copy') of six can in fact be found in the Python documentation. More clarification rather than correction perhaps.

comment:8 by Tim Graham, 11 years ago

Yes, I agree to keep the links are they are and add clarification if needed.

I also confirm that the linking issue is fixed with Sphinx 1.2b2 which docs.djangoproject.com is now using.

comment:9 by Daley Chetwynd, 11 years ago

I have submitted a pull request for this ticket fix.

As per timo's confirmation that the linking issue is fixed in Sphinx 1.2b2, I have not changed this. I have modified a few of the link targets, added a couple of extra sentences to clarify that Django uses a customised version of the six module and changed a section header.

comment:10 by Tim Graham <timograham@…>, 11 years ago

Resolution: fixed
Status: assignedclosed

In a53caf28bf2ab29cf4e78a968b3887ddb6d6e83d:

Fixed #20830 -- Clarified that Django uses a customized version of six.

Thanks glarrain for the suggestion.

comment:11 by Tim Graham <timograham@…>, 11 years ago

In c695f293e3ce74657268e532ee69ae64c92bfa1c:

[1.5.x] Fixed #20830 -- Clarified that Django uses a customized version of six.

Thanks glarrain for the suggestion.

Backport of a53caf28bf from master

comment:12 by Tim Graham <timograham@…>, 11 years ago

In 5e549e7efe7fc5b29124846278a6b30332e40dc4:

[1.6.x] Fixed #20830 -- Clarified that Django uses a customized version of six.

Thanks glarrain for the suggestion.

Backport of a53caf28bf from master

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