Project

Profile

Help

Issue #3355

Getting an error building docs with Sphinx 1.7

Added by daviddavis over 1 year ago. Updated 6 months ago.

Status:
MODIFIED
Priority:
Normal
Assignee:
Category:
-
Sprint/Milestone:
Start date:
Due date:
Severity:
2. Medium
Version:
Platform Release:
Blocks Release:
OS:
Backwards Incompatible:
No
Triaged:
Yes
Groomed:
No
Sprint Candidate:
No
Tags:
QA Contact:
Complexity:
Smash Test:
Verified:
No
Verification Required:
No
Sprint:
Sprint 32

Description

A new version of sphinx was released today and it fails to build our docs:

/home/vagrant/devel/pulp/pulpcore/pulpcore/app/serializers/base.py:docstring of pulpcore.app.serializers.base.ModelSerializer.create:5:Inline strong start-string without end-string.

This previously worked with Sphinx 1.6.7.

Associated revisions

Revision f6be2d71 View on GitHub
Added by werwty over 1 year ago

Add docstring to fix Sphinx 1.7

closes #3355
https://pulp.plan.io/issues/3355

Revision f6be2d71 View on GitHub
Added by werwty over 1 year ago

Add docstring to fix Sphinx 1.7

closes #3355
https://pulp.plan.io/issues/3355

Revision f6be2d71 View on GitHub
Added by werwty over 1 year ago

Add docstring to fix Sphinx 1.7

closes #3355
https://pulp.plan.io/issues/3355

History

#1 Updated by daviddavis over 1 year ago

Here are the lines causing the problems:

https://github.com/encode/django-rest-framework/blob/master/rest_framework/serializers.py#L888
https://github.com/encode/django-rest-framework/blob/master/rest_framework/serializers.py#L895

Escaping the asterisks in my local copy of this file with backslashes fixed the problem for me.

#2 Updated by dalley over 1 year ago

  • Sprint/Milestone set to 54
  • Triaged changed from No to Yes

#3 Updated by daviddavis over 1 year ago

One thing I found that fixes the problem is to add docstring to ModelSerializer.create0. It looks like this prevents sphinx from looking up and parsing the docstring from DRF's ModelSerializer.create method (which has the offending problem). I don't think this is a good long-term solution though.

[0] https://github.com/pulp/pulp/blob/3.0-dev/pulpcore/pulpcore/app/serializers/base.py#L105

#4 Updated by bizhang over 1 year ago

I opened a PR to upstream django-rest-framework, but it was rejected :(
https://github.com/encode/django-rest-framework/pull/5832

I think the next best solution is to go with @daviddavis's proposal in https://pulp.plan.io/issues/3355#note-3

#5 Updated by bizhang over 1 year ago

  • Status changed from NEW to POST
  • Assignee set to bizhang

#6 Updated by werwty over 1 year ago

  • Status changed from POST to MODIFIED

#7 Updated by bmbouter over 1 year ago

  • Sprint set to Sprint 32

#8 Updated by bmbouter over 1 year ago

  • Sprint/Milestone deleted (54)

#9 Updated by dkliban@redhat.com over 1 year ago

  • Sprint/Milestone set to 3.0

#10 Updated by bmbouter 6 months ago

  • Tags deleted (Pulp 3, Pulp 3 MVP)

Please register to edit this issue

Also available in: Atom PDF