Skip to content

Commit d5efa89

Browse files
chrisjsewellchrisjsewell
authored
Improve option syntax (#10)
The panel level options now use the same format as normal options, e.g. card `+= shadow` to `:card: + shadow`, whereby a `+` at the start indicates additive behaviour. Also, the delimiters are now configured as regexes, for greater flexibility, and the default panel delimiter has been changed back from `...` to `---`.
1 parent b8d6b36 commit d5efa89

4 files changed

Lines changed: 141 additions & 112 deletions

File tree

‎README.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -14,15 +14,15 @@ and [cards layout](https://getbootstrap.com/docs/4.0/components/card/).
1414
1515
Content of the top-left panel
1616
17-
...
17+
---
1818
1919
Content of the top-right panel
2020
21-
...
21+
---
2222
2323
Content of the bottom-left panel
2424
25-
...
25+
---
2626
2727
Content of the bottom-right panel
2828
```

‎docs/index.rst‎

Lines changed: 80 additions & 68 deletions
Original file line numberDiff line numberDiff line change
@@ -15,31 +15,31 @@ and `cards layout <https://getbootstrap.com/docs/4.0/components/card/>`_.
1515
1616
Content of the top-left panel
1717
18-
...
18+
---
1919
2020
Content of the top-right panel
2121
22-
...
22+
---
2323
2424
Content of the bottom-left panel
2525
26-
...
26+
---
2727
2828
Content of the bottom-right panel
2929
3030
.. panels::
3131

3232
Content of the top-left panel
3333

34-
...
34+
---
3535

3636
Content of the top-right panel
3737

38-
...
38+
---
3939

4040
Content of the bottom-left panel
4141

42-
...
42+
---
4343

4444
Content of the bottom-right panel
4545

@@ -77,12 +77,12 @@ This extension includes the bootstrap 4 CSS classes relevant to panels.
7777
They will be loaded by default but, if you are already using a bootstrap theme,
7878
you can disable this by adding ``panels_add_boostrap_css = False`` to your ``conf.py``.
7979

80-
You can also change the delimiters used by adding ``panel_delimiters`` to your ``conf.py``,
80+
You can also change the delimiter regexes used by adding ``panel_delimiters`` to your ``conf.py``,
8181
e.g. the default value (panels, header, footer) is:
8282

8383
.. code-block:: python
8484
85-
panels_delimiters = (".", "^", "+")
85+
panels_delimiters = (r"^\-{3,}$", r"^\^{3,}$", r"^\+{3,}$")
8686
8787
8888
Detailed Examples
@@ -91,11 +91,23 @@ Detailed Examples
9191
Grid Layout
9292
-----------
9393

94-
Panels are split by three or more `...` characters.
94+
Panels are split by three or more `-` characters.
9595
The layout of panels is then set by using the bootstrap classes.
9696
Default classes for all panels may be set in the directive options,
9797
then panel specific classes can be added at the start of each panel.
98-
`=` will reset the classes, or `+=` will add to the default classes.
98+
99+
By default the new classes will override those set previously
100+
(as defaults or in the top level options),
101+
but starting the option value with `+` will make the classes additive.
102+
For example the following options will set the first panel's card to have both the `shadow` and `bg-info` classes:
103+
104+
.. code-block:: rst
105+
106+
.. panels::
107+
:card: shadow
108+
109+
---
110+
:card: + bg-info
99111
100112
.. seealso::
101113

@@ -110,35 +122,35 @@ then panel specific classes can be added at the start of each panel.
110122
111123
.. panels::
112124
:container: container pb-4
113-
:column: col-lg-6 col-md-6 col-sm-6 col-xs-12
125+
:column: col-lg-6 col-md-6 col-sm-6 col-xs-12 p-2
114126
:card: shadow
115127
116128
.. code-block:: rst
117129
118130
.. panels::
119131
:container: container-lg pb-3
120-
:column: col-lg-4 col-md-4 col-sm-6 col-xs-12
132+
:column: col-lg-4 col-md-4 col-sm-6 col-xs-12 p-2
121133
122134
panel1
123-
...
135+
---
124136
panel2
125-
...
137+
---
126138
panel3
127-
...
128-
column = col-lg-12
139+
---
140+
:column: col-lg-12 p-2
129141
panel4
130142
131143
.. panels::
132144
:container: container-lg pb-3
133-
:column: col-lg-4 col-md-4 col-sm-6 col-xs-12
145+
:column: col-lg-4 col-md-4 col-sm-6 col-xs-12 p-2
134146

135147
panel1
136-
...
148+
---
137149
panel2
138-
...
150+
---
139151
panel3
140-
...
141-
column = col-lg-12
152+
---
153+
:column: col-lg-12 p-2
142154
panel4
143155

144156
Card Layout
@@ -166,7 +178,7 @@ split by three or more `^^^` and `+++` respectively.
166178
++++++++++++++
167179
panel 1 footer
168180
169-
...
181+
---
170182
171183
panel 2 header
172184
^^^^^^^^^^^^^^
@@ -188,7 +200,7 @@ split by three or more `^^^` and `+++` respectively.
188200
++++++++++++++
189201
panel 1 footer
190202

191-
...
203+
---
192204

193205
panel 2 header
194206
^^^^^^^^^^^^^^
@@ -218,7 +230,7 @@ You can add your own CSS (see
218230
but it is advised you use the built-in bootstrap classes:
219231

220232
- `Card colouring <https://getbootstrap.com/docs/4.0/utilities/colors/>`_ contextual classes: `bg-primary`, `bg-success`, `bg-info`, `bg-warning`, `bg-danger`, `bg-secondary`, `bg-dark` and `bg-light`.
221-
- `Padding and margins <https://getbootstrap.com/docs/4.0/utilities/spacing/>`_: `border-0`, `p-2`, `m-2`, ...
233+
- `Padding and margins <https://getbootstrap.com/docs/4.0/utilities/spacing/>`_: `border-0`, `p-2`, `m-2`, ---
222234
- `Text alignment <https://getbootstrap.com/docs/4.0/utilities/text/#text-alignment>`_: `text-justify`, `text-left`, `text-center`, `text-right`
223235

224236
.. code-block:: rst
@@ -228,8 +240,8 @@ but it is advised you use the built-in bootstrap classes:
228240
:header: text-center
229241
:footer: text-right
230242
231-
...
232-
column += p-1
243+
---
244+
:column: + p-1
233245
234246
panel 1 header
235247
^^^^^^^^^^^^^^
@@ -239,11 +251,11 @@ but it is advised you use the built-in bootstrap classes:
239251
++++++++++++++
240252
panel 1 footer
241253
242-
...
243-
column += p-1 text-center border-0
244-
body = bg-info
245-
header = bg-success
246-
footer = bg-secondary
254+
---
255+
:column: + p-1 text-center border-0
256+
:body: bg-info
257+
:header: bg-success
258+
:footer: bg-secondary
247259
248260
panel 2 header
249261
^^^^^^^^^^^^^^
@@ -258,8 +270,8 @@ but it is advised you use the built-in bootstrap classes:
258270
:header: text-center
259271
:footer: text-right
260272

261-
...
262-
column += p-1
273+
---
274+
:column: + p-1
263275

264276
panel 1 header
265277
^^^^^^^^^^^^^^
@@ -269,11 +281,11 @@ but it is advised you use the built-in bootstrap classes:
269281
++++++++++++++
270282
panel 1 footer
271283

272-
...
273-
column += p-1 text-center border-0
274-
body = bg-info
275-
header = bg-success
276-
footer = bg-secondary
284+
---
285+
:column: + p-1 text-center border-0
286+
:body: bg-info
287+
:header: bg-success
288+
:footer: bg-secondary
277289

278290
panel 2 header
279291
^^^^^^^^^^^^^^
@@ -296,9 +308,9 @@ but classes can also be used to add padding:
296308
.. panels::
297309
:img-top-cls: pl-5 pr-5
298310
299-
...
300-
img-top = _static/ebp-logo.png
301-
img-bottom = _static/footer-banner.jpg
311+
---
312+
:img-top: _static/ebp-logo.png
313+
:img-bottom: _static/footer-banner.jpg
302314
303315
header 1
304316
^^^^^^^^
@@ -310,10 +322,10 @@ but classes can also be used to add padding:
310322
++++++
311323
tail 1
312324
313-
...
314-
img-top = _static/sphinx-logo.png
315-
img-top-cls += bg-success
316-
img-bottom = _static/footer-banner.jpg
325+
---
326+
:img-top: _static/sphinx-logo.png
327+
:img-top-cls: + bg-success
328+
:img-bottom: _static/footer-banner.jpg
317329
318330
header 2
319331
^^^^^^^^
@@ -327,9 +339,9 @@ but classes can also be used to add padding:
327339
:img-top-cls: pl-5 pr-5
328340
:body: text-center
329341

330-
...
331-
img-top = _static/ebp-logo.png
332-
img-bottom = _static/footer-banner.jpg
342+
---
343+
:img-top: _static/ebp-logo.png
344+
:img-bottom: _static/footer-banner.jpg
333345

334346
header 1
335347
^^^^^^^^
@@ -341,10 +353,10 @@ but classes can also be used to add padding:
341353
++++++
342354
tail 1
343355

344-
...
345-
img-top = _static/sphinx-logo.png
346-
img-top-cls += bg-success
347-
img-bottom = _static/footer-banner.jpg
356+
---
357+
:img-top: _static/sphinx-logo.png
358+
:img-top-cls: + bg-success
359+
:img-bottom: _static/footer-banner.jpg
348360

349361
header 2
350362
^^^^^^^^
@@ -366,8 +378,8 @@ Additional Examples
366378
:header: border-0
367379
:footer: border-0
368380
369-
...
370-
card += bg-warning
381+
---
382+
:card: + bg-warning
371383
372384
header
373385
^^^^^^
@@ -377,9 +389,9 @@ Additional Examples
377389
++++++
378390
footer
379391
380-
...
381-
card += bg-info
382-
footer += bg-danger
392+
---
393+
:card: + bg-info
394+
:footer: + bg-danger
383395
384396
header
385397
^^^^^^
@@ -389,9 +401,9 @@ Additional Examples
389401
++++++
390402
footer
391403
392-
...
393-
column = col-lg-12
394-
card += bg-success text-center
404+
---
405+
:column: col-lg-12 p-3
406+
:card: + bg-success text-center
395407
396408
Content of the bottom panel
397409
@@ -403,8 +415,8 @@ Additional Examples
403415
:header: border-0
404416
:footer: border-0
405417

406-
...
407-
card += bg-warning
418+
---
419+
:card: + bg-warning
408420

409421
header
410422
^^^^^^
@@ -414,9 +426,9 @@ Additional Examples
414426
++++++
415427
footer
416428

417-
...
418-
card += bg-info
419-
footer += bg-danger
429+
---
430+
:card: + bg-info
431+
:footer: + bg-danger
420432

421433
header
422434
^^^^^^
@@ -426,9 +438,9 @@ Additional Examples
426438
++++++
427439
footer
428440

429-
...
430-
column = col-lg-12 p-3
431-
card += bg-success text-center
441+
---
442+
:column: col-lg-12 p-3
443+
:card: + bg-success text-center
432444

433445
Content of the bottom panel
434446

0 commit comments

Comments
 (0)