Project

Profile

Help

Issue #3355

Getting an error building docs with Sphinx 1.7

Added by daviddavis over 2 years ago. Updated 6 months ago.

Status:
CLOSED - CURRENTRELEASE
Priority:
Normal
Assignee:
Category:
-
Sprint/Milestone:
Start date:
Due date:
Severity:
2. Medium
Version:
Platform Release:
Blocks Release:
OS:
Triaged:
Yes
Groomed:
No
Sprint Candidate:
No
Tags:
QA Contact:
Complexity:
Smash Test:
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 2 years 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 2 years ago

Add docstring to fix Sphinx 1.7

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

History

#1 Updated by daviddavis over 2 years 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 2 years ago

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

#3 Updated by daviddavis over 2 years ago

One thing I found that fixes the problem is to add docstring to ModelSerializer.create[0]. 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 2 years 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 2 years ago

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

#6 Updated by werwty over 2 years ago

  • Status changed from POST to MODIFIED

#7 Updated by bmbouter about 2 years ago

  • Sprint set to Sprint 32

#8 Updated by bmbouter about 2 years ago

  • Sprint/Milestone deleted (54)

#9 Updated by dkliban@redhat.com about 2 years ago

  • Sprint/Milestone set to 3.0.0

#10 Updated by bmbouter about 1 year ago

  • Tags deleted (Pulp 3, Pulp 3 MVP)

#11 Updated by bmbouter 6 months ago

  • Status changed from MODIFIED to CLOSED - CURRENTRELEASE

Please register to edit this issue

Also available in: Atom PDF