Opened 4 years ago

Closed 3 years ago

#7329 defect closed fixed (fixed)

twisted.python.usage.Options documentation has improperly rendering code blocks

Reported by: Julian Berman Owned by: Jean-Paul Calderone
Priority: normal Milestone:
Component: core Keywords: documentation easy
Cc: Branch: branches/usage-docstring-formatting-7329
branch-diff, diff-cov, branch-cov, buildbot
Author: rwall

Description

The examples on this page render literally rather than preformatted.

E.g.:

optFlags is assigned a list of lists. Each list represents a flag parameter, as so:

| optFlags = ['quiet', 'q', 'Be vewy vewy quiet.'?

Change History (8)

comment:1 Changed 3 years ago by fbrennen

Added a patch for this in github. Find the pull request here: https://github.com/twisted/twisted/pull/48

comment:2 Changed 3 years ago by Richard Wall

Author: rwall
Branch: branches/usage-docstring-formatting-7329

(In [43149]) Branching to usage-docstring-formatting-7329.

comment:3 Changed 3 years ago by Richard Wall

Keywords: review added

I merged fbrennen's PR into a twisted branch and pushed the build button.

Ready for review.

comment:4 Changed 3 years ago by Adam Dangoor

Note that https://twistedmatrix.com/trac/ticket/7683 overlaps this issue and also has a patch for (some of?) these page rendering issues.

comment:5 Changed 3 years ago by Adi Roiban

#7683 is fine. do we also need this patch?

Maybe is better to apply these changes in #7683 and merge them together in #7683

comment:6 Changed 3 years ago by Jean-Paul Calderone

#7683 is fine. do we also need this patch?

This work was done first. Perhaps you should ask if we also need #7683, given the work done here?

comment:7 Changed 3 years ago by Jean-Paul Calderone

Keywords: review removed
Owner: set to Jean-Paul Calderone
Status: newassigned

I merged fbrennen's PR into a twisted branch and pushed the build button.

Thanks Richard!

And thanks for this fix fbrennen. Sorry about the long delay on getting it reviewed.

These changes look good to me apart from the whitespace introduced before :: and the new : introduced to make a :::. Both of those seem to make rendering of the API documentation worse.

I'm going to back out those changes, make sure the rendering of the examples still looks good, and then merge. Thanks again.

comment:8 Changed 3 years ago by Jean-Paul Calderone

Resolution: fixed
Status: assignedclosed

(In [43485]) Merge usage-docstring-formatting-7329

Fixes: #7329 Author: fbrennen Reviewer: exarkun

Fix invalid epytext markup around the API documentation examples for twisted.python.usage.Options.

Note: See TracTickets for help on using tickets.