Skip to content

Commit d58bf18

Browse files
brechtmbrechtm
committed
Sphinx frontend: support versionmodified admonitions (fixes #440)
1 parent fa6c68e commit d58bf18

File tree

9 files changed

+225
-9
lines changed

9 files changed

+225
-9
lines changed

‎CHANGES.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,8 @@ Release 0.5.6 (in development)
1919

2020
New Features:
2121

22+
* versionmodified directive support (versionadded, versionchanged,
23+
versionremoved, deprecated) (#440)
2224
* The style log now also shows the classes for each element (if any)
2325

2426
Changed:

‎src/rinoh/data/stylesheets/sphinx.rts‎

Lines changed: 39 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -402,11 +402,6 @@ base=body
402402
space_above=1pt
403403

404404

405-
# (Sphinx) version added/changed & deprecated
406-
407-
[versionmodified]
408-
font_slant=ITALIC
409-
410405
# (Sphinx) object descriptions
411406

412407
[object description]
@@ -597,6 +592,45 @@ base=admonition
597592
border_top=none
598593
border_bottom=none
599594

595+
[versionmodified : Admonition]
596+
base=builtin admonition
597+
space_above=2pt
598+
space_below=2pt
599+
padding_top=0
600+
padding_bottom=0pt
601+
border_top=none
602+
border_bottom=none
603+
604+
[versionmodified inline title : StyledText]
605+
base=admonition inline title
606+
# title already includes a trailing space
607+
after = ''
608+
609+
[versionadded]
610+
base=versionmodified
611+
612+
[versionadded inline title]
613+
base=versionmodified inline title
614+
615+
[versionchanged]
616+
base=versionmodified
617+
618+
[versionchanged inline title]
619+
base=versionmodified inline title
620+
621+
[versionremoved]
622+
base=versionmodified
623+
624+
[versionremoved inline title]
625+
base=versionmodified inline title
626+
627+
[deprecated]
628+
base=versionmodified
629+
630+
[deprecated inline title]
631+
base=versionmodified inline title
632+
633+
600634
[header_footer:Paragraph]
601635
base=default
602636
typeface=$(sans_typeface)

‎src/rinoh/frontend/sphinx/nodes.py‎

Lines changed: 18 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -225,8 +225,24 @@ class SeeAlso(rst.Admonition):
225225
pass
226226

227227

228-
class VersionModified(DocutilsGroupingNode):
229-
pass
228+
class VersionModified(rst.Admonition):
229+
def build_flowable(self):
230+
subtype = self.attributes['type']
231+
title_class = subtype[len('version'):] if subtype.startswith('version') else subtype
232+
233+
def pop_title(items):
234+
"""Remove and return the admonition title from the paragraph"""
235+
first_item = items[0]
236+
if title_class in first_item.classes:
237+
del items[0]
238+
return first_item
239+
return pop_title(first_item)
240+
241+
children = self.children_flowables()
242+
first_paragraph = children[0]
243+
custom_title = pop_title(first_paragraph.content)
244+
return self.grouped_flowables_class(children, title=custom_title,
245+
style=subtype)
230246

231247

232248
# special nodes

‎src/rinoh/stylesheets/matcher.py‎

Lines changed: 20 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -203,7 +203,26 @@
203203

204204
# (Sphinx) version added/changed & deprecated
205205

206-
matcher('versionmodified', StyledText.like(classes=['versionmodified']))
206+
vermod = matcher('versionmodified', Admonition.like('versionmodified'))
207+
matcher('versionmodified title', vermod / Paragraph.like('title'))
208+
matcher('versionmodified inline title', vermod / Paragraph.like('title'))
209+
matcher('versionmodified inline title', vermod / ... / StyledText.like('inline title'))
210+
211+
veradd = matcher('versionadded', Admonition.like('versionadded'))
212+
matcher('versionadded title', veradd / Paragraph.like('title'))
213+
matcher('versionadded inline title', veradd / ... / StyledText.like('inline title'))
214+
215+
verrem = matcher('versionremoved', Admonition.like('versionremoved'))
216+
matcher('versionremoved title', verrem / Paragraph.like('title'))
217+
matcher('versionremoved inline title', verrem / ... / StyledText.like('inline title'))
218+
219+
verchg = matcher('versionchanged', Admonition.like('versionchanged'))
220+
matcher('versionchanged title', verchg / Paragraph.like('title'))
221+
matcher('versionchanged inline title', verchg / ... / StyledText.like('inline title'))
222+
223+
deprec = matcher('deprecated', Admonition.like('deprecated'))
224+
matcher('deprecated title', deprec / Paragraph.like('title'))
225+
matcher('deprecated inline title', deprec / ... / StyledText.like('inline title'))
207226

208227
# (Sphinx) object descriptions
209228

‎tests_regression/rst/sphinx_admonition.pdf‎

3.82 KB
Binary file not shown.

‎tests_regression/rst/sphinx_admonition.pxml‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
<document source="/Users/brechtm/Code/rinohtype/tests_regression/rst/index.rst" translation_progress="{'total': 0, 'translated': 0}">
2+
<seealso>
3+
<paragraph>
4+
This other place.
5+
<versionmodified type="versionadded" version="3">
6+
<paragraph translatable="False">
7+
<inline classes="versionmodified added">
8+
Added in version 3:
9+
Don't try to use this in an older version!
10+
<versionmodified type="versionchanged" version="2.3">
11+
<paragraph translatable="False">
12+
<inline classes="versionmodified changed">
13+
Changed in version 2.3:
14+
Different behavior, so be careful when upgrading!
15+
<versionmodified type="versionremoved" version="3.14">
16+
<paragraph translatable="False">
17+
<inline classes="versionmodified removed">
18+
Removed in version 3.14:
19+
It's gone, sorry!
20+
<versionmodified type="deprecated" version="2.5">
21+
<paragraph translatable="False">
22+
<inline classes="versionmodified deprecated">
23+
Deprecated since version 2.5:
24+
Use something else instead.
25+
This feature will be removed in a future version.

‎tests_regression/rst/sphinx_admonition.rst‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
2+
.. seealso:: This other place.
3+
4+
.. versionadded:: 3 Don't try to use this in an older version!
5+
6+
.. versionchanged:: 2.3 Different behavior, so be careful when upgrading!
7+
8+
.. versionremoved:: 3.14 It's gone, sorry!
9+
10+
.. deprecated:: 2.5 Use something else instead.
11+
This feature will be removed in a future version.

‎tests_regression/rst/sphinx_admonition.stylelog‎

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
---------------------------------- page 1 ----------------------------------
2+
#### FlowablesContainer('background')
3+
StaticGroupedFlowables()
4+
#### FootnoteContainer('footnotes')
5+
StaticGroupedFlowables()
6+
#### DownExpandingContainer('floats')
7+
StaticGroupedFlowables()
8+
#### ChainedContainer('column1')
9+
StaticGroupedFlowables()
10+
DocumentTree() index.rst <document>
11+
Admonition() index.rst <seealso>
12+
> (0,0,0,1,2) seealso admonition [Sphinx] > admonition
13+
(0,0,0,0,2) admonition [Sphinx] > DEFAULT
14+
Paragraph('See also', style='title')
15+
x (0,0,1,1,4) seealso admonition title
16+
> (0,0,1,0,4) admonition title [Sphinx] > body
17+
(0,0,1,0,2) title [Sphinx] > default
18+
(0,0,0,0,2) body [Sphinx] > default
19+
SingleStyledText('See also')
20+
Paragraph('This other place.') index.rst:2 <paragraph>
21+
> (0,0,0,0,2) body [Sphinx] > default
22+
MixedStyledText('This other place.')
23+
MixedStyledText('This other place.')
24+
SingleStyledText('This other place.')
25+
Admonition(style='versionadded') index.rst:4 <versionmodified>
26+
> (0,0,1,0,2) versionadded [Sphinx] > versionmodified
27+
(0,0,0,0,2) admonition [Sphinx] > DEFAULT
28+
AdmonitionTitleParagraph('Added in version 3: Don't try to...') index.rst:5 <paragraph>
29+
x (1,0,0,0,4) admonition title paragraph
30+
> (0,0,0,0,1) body [Sphinx] > default
31+
MixedStyledText('Added in version 3: Don't try to...')
32+
MixedStyledText('Added in version 3: Don't try to...')
33+
MixedStyledText('Added in version 3: ', style='inline title')
34+
> (0,0,2,0,3) versionadded inline title [Sphinx] > versionmodified inline title
35+
(0,0,1,0,3) admonition inline title [Sphinx] > admonition title
36+
MixedStyledText('Added in version 3: ') index.rst:5 <inline>
37+
SingleStyledText('Added in version 3: ')
38+
MixedStyledText('Don't try to use this in an olde...')
39+
MixedStyledText('Don't try to use this in an olde...')
40+
SingleStyledText('Don't try to use this in an olde...')
41+
Admonition(style='versionchanged') index.rst:6 <versionmodified>
42+
> (0,0,1,0,2) versionchanged [Sphinx] > versionmodified
43+
(0,0,0,0,2) admonition [Sphinx] > DEFAULT
44+
AdmonitionTitleParagraph('Changed in version 2.3: Differen...') index.rst:7 <paragraph>
45+
x (1,0,0,0,4) admonition title paragraph
46+
> (0,0,0,0,1) body [Sphinx] > default
47+
MixedStyledText('Changed in version 2.3: Differen...')
48+
MixedStyledText('Changed in version 2.3: Differen...')
49+
MixedStyledText('Changed in version 2.3: ', style='inline title')
50+
> (0,0,2,0,3) versionchanged inline title [Sphinx] > versionmodified inline title
51+
(0,0,1,0,3) admonition inline title [Sphinx] > admonition title
52+
MixedStyledText('Changed in version 2.3: ') index.rst:7 <inline>
53+
SingleStyledText('Changed in version 2.3: ')
54+
MixedStyledText('Different behavior, so be carefu...')
55+
MixedStyledText('Different behavior, so be carefu...')
56+
SingleStyledText('Different behavior, so be carefu...')
57+
MixedStyledText('Changed in version 2.3: Differen...')
58+
MixedStyledText('Changed in version 2.3: Differen...')
59+
MixedStyledText('Changed in version 2.3: ', style='inline title')
60+
> (0,0,2,0,3) versionchanged inline title [Sphinx] > versionmodified inline title
61+
(0,0,1,0,3) admonition inline title [Sphinx] > admonition title
62+
MixedStyledText('Changed in version 2.3: ') index.rst:7 <inline>
63+
SingleStyledText('Changed in version 2.3: ')
64+
MixedStyledText('Different behavior, so be carefu...')
65+
MixedStyledText('Different behavior, so be carefu...')
66+
SingleStyledText('Different behavior, so be carefu...')
67+
Admonition(style='versionremoved') index.rst:8 <versionmodified>
68+
> (0,0,1,0,2) versionremoved [Sphinx] > versionmodified
69+
(0,0,0,0,2) admonition [Sphinx] > DEFAULT
70+
AdmonitionTitleParagraph('Removed in version 3.14: It's go...') index.rst:9 <paragraph>
71+
x (1,0,0,0,4) admonition title paragraph
72+
> (0,0,0,0,1) body [Sphinx] > default
73+
MixedStyledText('Removed in version 3.14: It's go...')
74+
MixedStyledText('Removed in version 3.14: It's go...')
75+
MixedStyledText('Removed in version 3.14: ', style='inline title')
76+
> (0,0,2,0,3) versionremoved inline title [Sphinx] > versionmodified inline title
77+
(0,0,1,0,3) admonition inline title [Sphinx] > admonition title
78+
MixedStyledText('Removed in version 3.14: ') index.rst:9 <inline>
79+
SingleStyledText('Removed in version 3.14: ')
80+
MixedStyledText('It's gone, sorry!')
81+
MixedStyledText('It's gone, sorry!')
82+
SingleStyledText('It's gone, sorry!')
83+
Admonition(style='deprecated') index.rst:10 <versionmodified>
84+
> (0,0,1,0,2) deprecated [Sphinx] > versionmodified
85+
(0,0,0,0,2) admonition [Sphinx] > DEFAULT
86+
AdmonitionTitleParagraph('Deprecated since version 2.5: Us...') index.rst:11 <paragraph>
87+
x (1,0,0,0,4) admonition title paragraph
88+
> (0,0,0,0,1) body [Sphinx] > default
89+
MixedStyledText('Deprecated since version 2.5: Us...')
90+
MixedStyledText('Deprecated since version 2.5: Us...')
91+
MixedStyledText('Deprecated since version 2.5: ', style='inline title')
92+
> (0,0,2,0,3) deprecated inline title [Sphinx] > versionmodified inline title
93+
(0,0,1,0,3) admonition inline title [Sphinx] > admonition title
94+
MixedStyledText('Deprecated since version 2.5: ') index.rst:11 <inline>
95+
SingleStyledText('Deprecated since version 2.5: ')
96+
MixedStyledText('Use something else instead. This...')
97+
MixedStyledText('Use something else instead. This...')
98+
SingleStyledText('Use something else instead. This...')
99+
MixedStyledText('Deprecated since version 2.5: Us...')
100+
MixedStyledText('Deprecated since version 2.5: Us...')
101+
MixedStyledText('Deprecated since version 2.5: ', style='inline title')
102+
> (0,0,2,0,3) deprecated inline title [Sphinx] > versionmodified inline title
103+
(0,0,1,0,3) admonition inline title [Sphinx] > admonition title
104+
MixedStyledText('Deprecated since version 2.5: ') index.rst:11 <inline>
105+
SingleStyledText('Deprecated since version 2.5: ')
106+
MixedStyledText('Use something else instead. This...')
107+
MixedStyledText('Use something else instead. This...')
108+
SingleStyledText('Use something else instead. This...')

‎tests_regression/test_rst.py‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,8 +17,9 @@
1717
RST_PATH = Path(__file__).parent / 'rst'
1818

1919
MIN_SPHINX_VERSION = {
20-
'sphinx_inline_markup': '3.2',
20+
'sphinx_admonition': '7.3',
2121
'sphinx_collapsible': '8.2',
22+
'sphinx_inline_markup': '3.2',
2223
}
2324

2425

0 commit comments

Comments
 (0)