Code

Opened 9 months ago

Closed 7 months ago

Last modified 7 months ago

#20830 closed Bug (fixed)

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

Reported by: glarrain Owned by: dchetwynd
Component: Documentation Version: master
Severity: Normal Keywords: six, python3, afraid-to-commit
Cc: timograham@…, EvilDMP 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 EvilDMP)

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.

Attachments (0)

Change History (12)

comment:1 Changed 9 months ago by timo

  • Cc timograham@… added
  • Easy pickings unset
  • Needs documentation unset
  • Needs tests unset
  • Patch needs improvement unset
  • Summary changed from Bad URL in "Porting to Python 3 / Moved modules" to Bad URL for six.moves in "Porting to Python 3 / Moved modules"
  • Triage Stage changed from Unreviewed to Accepted

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 Changed 7 months ago by EvilDMP

  • Cc EvilDMP added
  • Description modified (diff)
  • Easy pickings set
  • Keywords python3, afraid-to-commit added; python3 removed

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 Changed 7 months ago by timo

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 Changed 7 months ago by dchetwynd

  • Owner changed from nobody to dchetwynd
  • Status changed from new to assigned

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

comment:5 Changed 7 months ago by dchetwynd

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 Changed 7 months ago by dchetwynd

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 7 months ago by dchetwynd (previous) (diff)

comment:7 Changed 7 months ago by EvilDMP

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 Changed 7 months ago by timo

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 Changed 7 months ago by dchetwynd

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 Changed 7 months ago by Tim Graham <timograham@…>

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

In a53caf28bf2ab29cf4e78a968b3887ddb6d6e83d:

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

Thanks glarrain for the suggestion.

comment:11 Changed 7 months ago by Tim Graham <timograham@…>

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 Changed 7 months ago by Tim Graham <timograham@…>

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

Add Comment

Modify Ticket

Change Properties
<Author field>
Action
as closed
as The resolution will be set. Next status will be 'closed'
The resolution will be deleted. Next status will be 'new'
Author


E-mail address and user name can be saved in the Preferences.

 
Note: See TracTickets for help on using tickets.