Skip to content

Commit 808090e

Browse files
committed
trying to fix formatting glitches
1 parent 72e0aef commit 808090e

File tree

12 files changed

+516
-351
lines changed

12 files changed

+516
-351
lines changed

.gitignore

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@ tests/test_orca/images/linux/failed/
1414
doc/python/raw.githubusercontent.com/
1515

1616
docs/
17+
docs_tmp/
1718

1819
# Don't ignore dataset files
1920
!*.csv.gz

Makefile

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,11 @@ commands:
1212
docs:
1313
${PYTHON} -m mkdocs build
1414

15+
## docs-tmp: rebuild documentation saving Markdown in ./tmp
16+
.PHONY: docs
17+
docs-tmp:
18+
MKDOCS_TEMP_DIR=./docs_tmp ${PYTHON} -m mkdocs build
19+
1520
## format: reformat code
1621
format:
1722
${PYTHON} -m ruff format ${CODE_DIRS}

bin/codegen/datatypes.py

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -218,6 +218,9 @@ def _subplot_re_match(self, prop):
218218
else:
219219
property_docstring = property_description
220220

221+
# Fix `][`.
222+
property_docstring = property_docstring.replace("][", "]\\[")
223+
221224
# Write get property
222225
buffer.write(
223226
f'''\

bin/codegen/utils.py

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -163,6 +163,9 @@ def format_description(desc):
163163
# replace {2D arrays} with 2D lists
164164
desc = desc.replace("{2D arrays}", "2D lists")
165165

166+
# replace '][' with ']\[' to avoid confusion with Markdown reference links
167+
desc = desc.replace("][", r"]\\[")
168+
166169
return desc
167170

168171

bin/generate_reference_pages.py

Lines changed: 35 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,32 +1,58 @@
11
"""Generate the code reference pages and navigation."""
22

3+
import os
34
from pathlib import Path
5+
46
import mkdocs_gen_files
57

8+
9+
# Saving Markdown files?
10+
temp_dir = os.getenv("MKDOCS_TEMP_DIR", None)
11+
if temp_dir is not None:
12+
temp_dir = Path(temp_dir)
13+
14+
# Set up the generation engine.
615
nav = mkdocs_gen_files.Nav()
716

17+
# Match each Python file.
818
for path in sorted(Path("plotly").rglob("*.py")):
19+
# Documentation path.
920
module_path = path.relative_to(".").with_suffix("")
1021
doc_path = path.relative_to(".").with_suffix(".md")
1122
full_doc_path = Path("reference", doc_path)
1223

24+
# Handle dunder special cases.
1325
parts = tuple(module_path.parts)
14-
1526
if parts[-1] == "__init__":
1627
parts = parts[:-1]
1728
doc_path = doc_path.with_name("index.md")
1829
full_doc_path = full_doc_path.with_name("index.md")
1930
elif parts[-1] == "__main__":
2031
continue
2132

33+
# Save constructed data.
2234
nav[parts] = doc_path.as_posix()
23-
24-
with mkdocs_gen_files.open(full_doc_path, "w") as fd:
25-
ident = ".".join(parts)
26-
fd.write(f"# {ident}\n\n")
27-
fd.write(f"::: {ident}")
28-
2935
mkdocs_gen_files.set_edit_path(full_doc_path, path)
3036

31-
with mkdocs_gen_files.open("reference/SUMMARY.md", "w") as nav_file:
32-
nav_file.writelines(nav.build_literate_nav())
37+
# Save in-memory file.
38+
with mkdocs_gen_files.open(full_doc_path, "w") as writer:
39+
ident = ".".join(parts)
40+
writer.write(f"# {ident}\n\n")
41+
writer.write(f"::: {ident}")
42+
43+
# Save to disk if requested.
44+
if temp_dir is not None:
45+
temp_path = temp_dir / doc_path
46+
temp_path.parent.mkdir(exist_ok=True, parents=True)
47+
with open(temp_path, "w") as writer:
48+
ident = ".".join(parts)
49+
writer.write(f"# {ident}\n\n")
50+
writer.write(f"::: {ident}")
51+
52+
# Generate navigation summary.
53+
with mkdocs_gen_files.open("reference/SUMMARY.md", "w") as writer:
54+
writer.writelines(nav.build_literate_nav())
55+
if temp_dir is not None:
56+
temp_path = temp_dir / "SUMMARY.md"
57+
with open(temp_path, "w") as writer:
58+
writer.writelines(nav.build_literate_nav())

plotly/_subplots.py

Lines changed: 13 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -122,9 +122,9 @@ def make_subplots(
122122
Per subplot specifications of subplot type, row/column spanning, and
123123
spacing.
124124
125-
ex1: specs=[[{}, {}], [{'colspan': 2}, None]]
125+
ex1: `specs=[[{}, {}], [{'colspan': 2}, None]\\]
126126
127-
ex2: specs=[[{'rowspan': 2}, {}], [None, {}]]
127+
ex2: `specs=[[{'rowspan': 2}, {}], [None, {}]\\]
128128
129129
- Indices of the outer list correspond to subplot grid rows
130130
starting from the top, if start_cell='top-left',
@@ -141,7 +141,7 @@ def make_subplots(
141141
142142
- Use None for a blank a subplot cell (or to move past a col/row span).
143143
144-
- Note that specs[0][0] has the specs of the 'start_cell' subplot.
144+
- Note that `specs[0][0\\] has the specs of the 'start_cell' subplot.
145145
146146
- Each item in 'specs' is a dictionary.
147147
The available keys are:
@@ -246,8 +246,8 @@ def make_subplots(
246246
>>> fig = make_subplots(rows=2)
247247
248248
This is the format of your plot grid:
249-
[ (1,1) xaxis1,yaxis1 ]
250-
[ (2,1) xaxis2,yaxis2 ]
249+
\\[ (1,1) xaxis1,yaxis1 \\]
250+
\\[ (2,1) xaxis2,yaxis2 \\]
251251
252252
>>> fig.add_scatter(y=[2, 1, 3], row=1, col=1) # doctest: +ELLIPSIS
253253
Figure(...)
@@ -262,8 +262,8 @@ def make_subplots(
262262
>>> fig = make_subplots(rows=2, shared_xaxes=True)
263263
264264
This is the format of your plot grid:
265-
[ (1,1) xaxis1,yaxis1 ]
266-
[ (2,1) xaxis2,yaxis2 ]
265+
\\[ (1,1) xaxis1,yaxis1 \\]
266+
\\[ (2,1) xaxis2,yaxis2 \\]
267267
268268
>>> fig.add_scatter(y=[2, 1, 3], row=1, col=1) # doctest: +ELLIPSIS
269269
Figure(...)
@@ -278,8 +278,8 @@ def make_subplots(
278278
... [{'colspan': 2}, None]])
279279
280280
This is the format of your plot grid:
281-
[ (1,1) xaxis1,yaxis1 ] [ (1,2) xaxis2,yaxis2 ]
282-
[ (2,1) xaxis3,yaxis3 - ]
281+
\\[ (1,1) xaxis1,yaxis1 ] [ (1,2) xaxis2,yaxis2 \\]
282+
\\[ (2,1) xaxis3,yaxis3 - \\]
283283
284284
>>> fig.add_trace(go.Scatter(x=[1,2,3], y=[2,1,2]), row=1, col=1) # doctest: +ELLIPSIS
285285
Figure(...)
@@ -294,10 +294,10 @@ def make_subplots(
294294
>>> fig = make_subplots(insets=[{'cell': (1,1), 'l': 0.7, 'b': 0.3}])
295295
296296
This is the format of your plot grid:
297-
[ (1,1) xaxis1,yaxis1 ]
297+
\\[ (1,1) xaxis1,yaxis1 \\]
298298
299299
With insets:
300-
[ xaxis2,yaxis2 ] over [ (1,1) xaxis1,yaxis1 ]
300+
\\[ xaxis2,yaxis2 ] over [ (1,1) xaxis1,yaxis1 \\]
301301
302302
>>> fig.add_scatter(x=[1,2,3], y=[2,1,1]) # doctest: +ELLIPSIS
303303
Figure(...)
@@ -310,8 +310,8 @@ def make_subplots(
310310
>>> fig = make_subplots(rows=2, subplot_titles=('Plot 1','Plot 2'))
311311
312312
This is the format of your plot grid:
313-
[ (1,1) x1,y1 ]
314-
[ (2,1) x2,y2 ]
313+
\\[ (1,1) x1,y1 \\]
314+
\\[ (2,1) x2,y2 \\]
315315
316316
>>> fig.add_scatter(x=[1,2,3], y=[2,1,2], row=1, col=1) # doctest: +ELLIPSIS
317317
Figure(...)

plotly/basedatatypes.py

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2320,8 +2320,8 @@ def append_trace(self, trace, row, col):
23202320
>>> fig = tools.make_subplots(rows=2)
23212321
23222322
This is the format of your plot grid:
2323-
[ (1,1) x1,y1 ]
2324-
[ (2,1) x2,y2 ]
2323+
\\[ (1,1) x1,y1 \\]
2324+
\\[ (2,1) x2,y2 \\]
23252325
23262326
>>> fig.append_trace(go.Scatter(x=[1,2,3], y=[2,1,2]), row=1, col=1)
23272327
>>> fig.append_trace(go.Scatter(x=[1,2,3], y=[2,1,2]), row=2, col=1)

plotly/express/_core.py

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -101,9 +101,9 @@ def reset(self):
101101
def set_mapbox_access_token(token):
102102
"""
103103
Arguments:
104-
token: A Mapbox token to be used in `plotly.express.scatter_mapbox` and \
105-
`plotly.express.line_mapbox` figures. See \
106-
https://docs.mapbox.com/help/how-mapbox-works/access-tokens/ for more details
104+
token (Mapbox token): A Mapbox token to be used in `plotly.express.scatter_mapbox` \
105+
and `plotly.express.line_mapbox` figures. See \
106+
https://docs.mapbox.com/help/how-mapbox-works/access-tokens/ for more details.
107107
"""
108108
global MAPBOX_TOKEN
109109
MAPBOX_TOKEN = token
@@ -115,7 +115,7 @@ def get_trendline_results(fig):
115115
the `trendline` argument set to `"ols"`).
116116
117117
Arguments:
118-
fig: the output of a `plotly.express` charting call
118+
fig (figure): the output of a `plotly.express` charting call
119119
Returns:
120120
A `pandas.DataFrame` with a column "px_fit_results" containing the `statsmodels`
121121
results objects, along with columns identifying the subset of the data the

plotly/figure_factory/_violin.py

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -513,7 +513,7 @@ def create_violin(
513513
>>> norm_params=[(0, 1.2), (0.7, 1), (-0.5, 1.4), (0.3, 1), (0.8, 0.9)]
514514
515515
>>> for i, letter in enumerate("ABCDE"):
516-
... y[gr == letter] *=norm_params[i][1]+ norm_params[i][0]
516+
... y[gr == letter] *= norm_params[i]\[1]+ norm_params[i]\[0]
517517
>>> df = pd.DataFrame(dict(Score=y, Group=gr))
518518
519519
>>> # create violin fig
@@ -540,7 +540,7 @@ def create_violin(
540540
>>> norm_params=[(0, 1.2), (0.7, 1), (-0.5, 1.4), (0.3, 1), (0.8, 0.9)]
541541
542542
>>> for i, letter in enumerate("ABCDE"):
543-
... y[gr == letter] *=norm_params[i][1]+ norm_params[i][0]
543+
... y[gr == letter] *= norm_params[i]\[1]+ norm_params[i]\[0]
544544
>>> df = pd.DataFrame(dict(Score=y, Group=gr))
545545
546546
>>> # define header params

plotly/subplots.py

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -105,7 +105,7 @@ def make_subplots(
105105
106106
- Use None for a blank a subplot cell (or to move past a col/row span).
107107
108-
- Note that specs[0][0] has the specs of the 'start_cell' subplot.
108+
- Note that `specs[0][0\] has the specs of the 'start_cell' subplot.
109109
110110
- Each item in 'specs' is a dictionary.
111111
The available keys are:
@@ -210,8 +210,8 @@ def make_subplots(
210210
>>> fig = make_subplots(rows=2)
211211
212212
This is the format of your plot grid:
213-
[ (1,1) xaxis1,yaxis1 ]
214-
[ (2,1) xaxis2,yaxis2 ]
213+
\[ (1,1) xaxis1,yaxis1 \]
214+
\[ (2,1) xaxis2,yaxis2 \]
215215
216216
>>> fig.add_scatter(y=[2, 1, 3], row=1, col=1) # doctest: +ELLIPSIS
217217
Figure(...)
@@ -226,8 +226,8 @@ def make_subplots(
226226
>>> fig = make_subplots(rows=2, shared_xaxes=True)
227227
228228
This is the format of your plot grid:
229-
[ (1,1) xaxis1,yaxis1 ]
230-
[ (2,1) xaxis2,yaxis2 ]
229+
\[ (1,1) xaxis1,yaxis1 \]
230+
\[ (2,1) xaxis2,yaxis2 \]
231231
232232
>>> fig.add_scatter(y=[2, 1, 3], row=1, col=1) # doctest: +ELLIPSIS
233233
Figure(...)
@@ -242,8 +242,8 @@ def make_subplots(
242242
... [{'colspan': 2}, None]])
243243
244244
This is the format of your plot grid:
245-
[ (1,1) xaxis1,yaxis1 ] [ (1,2) xaxis2,yaxis2 ]
246-
[ (2,1) xaxis3,yaxis3 - ]
245+
\[ (1,1) xaxis1,yaxis1 ] [ (1,2) xaxis2,yaxis2 \]
246+
\[ (2,1) xaxis3,yaxis3 - \]
247247
248248
>>> fig.add_trace(go.Scatter(x=[1,2,3], y=[2,1,2]), row=1, col=1) # doctest: +ELLIPSIS
249249
Figure(...)
@@ -258,10 +258,10 @@ def make_subplots(
258258
>>> fig = make_subplots(insets=[{'cell': (1,1), 'l': 0.7, 'b': 0.3}])
259259
260260
This is the format of your plot grid:
261-
[ (1,1) xaxis1,yaxis1 ]
261+
\[ (1,1) xaxis1,yaxis1 \]
262262
263263
With insets:
264-
[ xaxis2,yaxis2 ] over [ (1,1) xaxis1,yaxis1 ]
264+
\[ xaxis2,yaxis2 \] over \[ (1,1) xaxis1,yaxis1 \]
265265
266266
>>> fig.add_scatter(x=[1,2,3], y=[2,1,1]) # doctest: +ELLIPSIS
267267
Figure(...)
@@ -274,8 +274,8 @@ def make_subplots(
274274
>>> fig = make_subplots(rows=2, subplot_titles=('Plot 1','Plot 2'))
275275
276276
This is the format of your plot grid:
277-
[ (1,1) x1,y1 ]
278-
[ (2,1) x2,y2 ]
277+
\[ (1,1) x1,y1 \]
278+
\[ (2,1) x2,y2 \]
279279
280280
>>> fig.add_scatter(x=[1,2,3], y=[2,1,2], row=1, col=1) # doctest: +ELLIPSIS
281281
Figure(...)

0 commit comments

Comments
 (0)