Issue #3355: Getting an error building docs with Sphinx 1.7 - Pulp

Actions

Send by e-mail Copy link

Issue #3355

closed

Getting an error building docs with Sphinx 1.7

Added by daviddavis about 6 years ago. Updated over 4 years ago.

Status:

CLOSED - CURRENTRELEASE

Priority:

Normal

Assignee:

bizhang

Category:

Sprint/Milestone:

3.0.0

Start date:

Due date:

Estimated time:

Severity:

2. Medium

Version:

Platform Release:

OS:

Triaged:

Yes

Groomed:

Sprint Candidate:

Tags:

Sprint:

Sprint 32

Quarter:

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.

Actions

Copy link

Updated by daviddavis about 6 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.

Actions

Copy link

Updated by dalley about 6 years ago

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

Actions

Copy link

Updated by daviddavis about 6 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

Actions

Copy link