trying to fix formatting glitches

Author: gvwilson

.gitignore

@@ -14,6 +14,7 @@ tests/test_orca/images/linux/failed/
 doc/python/raw.githubusercontent.com/
 
 docs/
+docs_tmp/
 
 # Don't ignore dataset files
 !*.csv.gz

Makefile

@@ -12,6 +12,11 @@ commands:
 docs:
 	${PYTHON} -m mkdocs build
 
+## docs-tmp: rebuild documentation saving Markdown in ./tmp
+.PHONY: docs
+docs-tmp:
+	MKDOCS_TEMP_DIR=./docs_tmp ${PYTHON} -m mkdocs build
+
 ## format: reformat code
 format:
 	${PYTHON} -m ruff format ${CODE_DIRS}

bin/codegen/datatypes.py

@@ -218,6 +218,9 @@ def _subplot_re_match(self, prop):
         else:
             property_docstring = property_description
 
+        # Fix `][`.
+        property_docstring = property_docstring.replace("][", "]\\[")
+
         # Write get property
         buffer.write(
             f'''\

bin/codegen/utils.py

@@ -163,6 +163,9 @@ def format_description(desc):
     # replace {2D arrays} with 2D lists
     desc = desc.replace("{2D arrays}", "2D lists")
 
+    # replace '][' with ']\[' to avoid confusion with Markdown reference links
+    desc = desc.replace("][", r"]\\[")
+
     return desc
 
 

bin/generate_reference_pages.py

@@ -1,32 +1,58 @@
 """Generate the code reference pages and navigation."""
 
+import os
 from pathlib import Path
+
 import mkdocs_gen_files
 
+
+# Saving Markdown files?
+temp_dir = os.getenv("MKDOCS_TEMP_DIR", None)
+if temp_dir is not None:
+    temp_dir = Path(temp_dir)
+
+# Set up the generation engine.
 nav = mkdocs_gen_files.Nav()
 
+# Match each Python file.
 for path in sorted(Path("plotly").rglob("*.py")):
+    # Documentation path.
     module_path = path.relative_to(".").with_suffix("")
     doc_path = path.relative_to(".").with_suffix(".md")
     full_doc_path = Path("reference", doc_path)
 
+    # Handle dunder special cases.
     parts = tuple(module_path.parts)
-
     if parts[-1] == "__init__":
         parts = parts[:-1]
         doc_path = doc_path.with_name("index.md")
         full_doc_path = full_doc_path.with_name("index.md")
     elif parts[-1] == "__main__":
         continue
 
+    # Save constructed data.
     nav[parts] = doc_path.as_posix()
-
-    with mkdocs_gen_files.open(full_doc_path, "w") as fd:
-        ident = ".".join(parts)
-        fd.write(f"# {ident}\n\n")
-        fd.write(f"::: {ident}")
-
     mkdocs_gen_files.set_edit_path(full_doc_path, path)
 
-with mkdocs_gen_files.open("reference/SUMMARY.md", "w") as nav_file:
-    nav_file.writelines(nav.build_literate_nav())
+    # Save in-memory file.
+    with mkdocs_gen_files.open(full_doc_path, "w") as writer:
+        ident = ".".join(parts)
+        writer.write(f"# {ident}\n\n")
+        writer.write(f"::: {ident}")
+
+    # Save to disk if requested.
+    if temp_dir is not None:
+        temp_path = temp_dir / doc_path
+        temp_path.parent.mkdir(exist_ok=True, parents=True)
+        with open(temp_path, "w") as writer:
+            ident = ".".join(parts)
+            writer.write(f"# {ident}\n\n")
+            writer.write(f"::: {ident}")
+
+# Generate navigation summary.
+with mkdocs_gen_files.open("reference/SUMMARY.md", "w") as writer:
+    writer.writelines(nav.build_literate_nav())
+if temp_dir is not None:
+    temp_path = temp_dir / "SUMMARY.md"
+    with open(temp_path, "w") as writer:
+        writer.writelines(nav.build_literate_nav())

plotly/_subplots.py

@@ -122,9 +122,9 @@ def make_subplots(
         Per subplot specifications of subplot type, row/column spanning, and
         spacing.
 
-        ex1: specs=[[{}, {}], [{'colspan': 2}, None]]
+        ex1: `specs=[[{}, {}], [{'colspan': 2}, None]\\]
 
-        ex2: specs=[[{'rowspan': 2}, {}], [None, {}]]
+        ex2: `specs=[[{'rowspan': 2}, {}], [None, {}]\\]
 
         - Indices of the outer list correspond to subplot grid rows
           starting from the top, if start_cell='top-left',
@@ -141,7 +141,7 @@ def make_subplots(
 
         - Use None for a blank a subplot cell (or to move past a col/row span).
 
-        - Note that specs[0][0] has the specs of the 'start_cell' subplot.
+        - Note that `specs[0][0\\] has the specs of the 'start_cell' subplot.
 
         - Each item in 'specs' is a dictionary.
             The available keys are:
@@ -246,8 +246,8 @@ def make_subplots(
     >>> fig = make_subplots(rows=2)
 
     This is the format of your plot grid:
-    [ (1,1) xaxis1,yaxis1 ]
-    [ (2,1) xaxis2,yaxis2 ]
+    \\[ (1,1) xaxis1,yaxis1 \\]
+    \\[ (2,1) xaxis2,yaxis2 \\]
 
     >>> fig.add_scatter(y=[2, 1, 3], row=1, col=1) # doctest: +ELLIPSIS
     Figure(...)
@@ -262,8 +262,8 @@ def make_subplots(
     >>> fig = make_subplots(rows=2, shared_xaxes=True)
 
     This is the format of your plot grid:
-    [ (1,1) xaxis1,yaxis1 ]
-    [ (2,1) xaxis2,yaxis2 ]
+    \\[ (1,1) xaxis1,yaxis1 \\]
+    \\[ (2,1) xaxis2,yaxis2 \\]
 
     >>> fig.add_scatter(y=[2, 1, 3], row=1, col=1) # doctest: +ELLIPSIS
     Figure(...)
@@ -278,8 +278,8 @@ def make_subplots(
     ...                     [{'colspan': 2}, None]])
 
     This is the format of your plot grid:
-    [ (1,1) xaxis1,yaxis1 ]  [ (1,2) xaxis2,yaxis2 ]
-    [ (2,1) xaxis3,yaxis3           -              ]
+    \\[ (1,1) xaxis1,yaxis1 ]  [ (1,2) xaxis2,yaxis2 \\]
+    \\[ (2,1) xaxis3,yaxis3           -              \\]
 
     >>> fig.add_trace(go.Scatter(x=[1,2,3], y=[2,1,2]), row=1, col=1) # doctest: +ELLIPSIS
     Figure(...)
@@ -294,10 +294,10 @@ def make_subplots(
     >>> fig = make_subplots(insets=[{'cell': (1,1), 'l': 0.7, 'b': 0.3}])
 
     This is the format of your plot grid:
-    [ (1,1) xaxis1,yaxis1 ]
+    \\[ (1,1) xaxis1,yaxis1 \\]
 
     With insets:
-    [ xaxis2,yaxis2 ] over [ (1,1) xaxis1,yaxis1 ]
+    \\[ xaxis2,yaxis2 ] over [ (1,1) xaxis1,yaxis1 \\]
 
     >>> fig.add_scatter(x=[1,2,3], y=[2,1,1]) # doctest: +ELLIPSIS
     Figure(...)
@@ -310,8 +310,8 @@ def make_subplots(
     >>> fig = make_subplots(rows=2, subplot_titles=('Plot 1','Plot 2'))
 
     This is the format of your plot grid:
-    [ (1,1) x1,y1 ]
-    [ (2,1) x2,y2 ]
+    \\[ (1,1) x1,y1 \\]
+    \\[ (2,1) x2,y2 \\]
 
     >>> fig.add_scatter(x=[1,2,3], y=[2,1,2], row=1, col=1) # doctest: +ELLIPSIS
     Figure(...)

plotly/basedatatypes.py

@@ -2320,8 +2320,8 @@ def append_trace(self, trace, row, col):
         >>> fig = tools.make_subplots(rows=2)
 
         This is the format of your plot grid:
-        [ (1,1) x1,y1 ]
-        [ (2,1) x2,y2 ]
+        \\[ (1,1) x1,y1 \\]
+        \\[ (2,1) x2,y2 \\]
 
         >>> fig.append_trace(go.Scatter(x=[1,2,3], y=[2,1,2]), row=1, col=1)
         >>> fig.append_trace(go.Scatter(x=[1,2,3], y=[2,1,2]), row=2, col=1)

plotly/express/_core.py

@@ -101,9 +101,9 @@ def reset(self):
 def set_mapbox_access_token(token):
     """
     Arguments:
-        token: A Mapbox token to be used in `plotly.express.scatter_mapbox` and \
-        `plotly.express.line_mapbox` figures. See \
-        https://docs.mapbox.com/help/how-mapbox-works/access-tokens/ for more details
+        token (Mapbox token): A Mapbox token to be used in `plotly.express.scatter_mapbox` \
+        and `plotly.express.line_mapbox` figures. See \
+        https://docs.mapbox.com/help/how-mapbox-works/access-tokens/ for more details.
     """
     global MAPBOX_TOKEN
     MAPBOX_TOKEN = token
@@ -115,7 +115,7 @@ def get_trendline_results(fig):
     the `trendline` argument set to `"ols"`).
 
     Arguments:
-        fig: the output of a `plotly.express` charting call
+        fig (figure): the output of a `plotly.express` charting call
     Returns:
         A `pandas.DataFrame` with a column "px_fit_results" containing the `statsmodels`
         results objects, along with columns identifying the subset of the data the

plotly/figure_factory/_violin.py

@@ -513,7 +513,7 @@ def create_violin(
     >>> norm_params=[(0, 1.2), (0.7, 1), (-0.5, 1.4), (0.3, 1), (0.8, 0.9)]
 
     >>> for i, letter in enumerate("ABCDE"):
-    ...     y[gr == letter] *=norm_params[i][1]+ norm_params[i][0]
+    ...     y[gr == letter] *= norm_params[i]\[1]+ norm_params[i]\[0]
     >>> df = pd.DataFrame(dict(Score=y, Group=gr))
 
     >>> # create violin fig
@@ -540,7 +540,7 @@ def create_violin(
     >>> norm_params=[(0, 1.2), (0.7, 1), (-0.5, 1.4), (0.3, 1), (0.8, 0.9)]
 
     >>> for i, letter in enumerate("ABCDE"):
-    ...     y[gr == letter] *=norm_params[i][1]+ norm_params[i][0]
+    ...     y[gr == letter] *= norm_params[i]\[1]+ norm_params[i]\[0]
     >>> df = pd.DataFrame(dict(Score=y, Group=gr))
 
     >>> # define header params

plotly/subplots.py

@@ -105,7 +105,7 @@ def make_subplots(
 
         - Use None for a blank a subplot cell (or to move past a col/row span).
 
-        - Note that specs[0][0] has the specs of the 'start_cell' subplot.
+        - Note that `specs[0][0\] has the specs of the 'start_cell' subplot.
 
         - Each item in 'specs' is a dictionary.
             The available keys are:
@@ -210,8 +210,8 @@ def make_subplots(
     >>> fig = make_subplots(rows=2)
 
     This is the format of your plot grid:
-    [ (1,1) xaxis1,yaxis1 ]
-    [ (2,1) xaxis2,yaxis2 ]
+    \[ (1,1) xaxis1,yaxis1 \]
+    \[ (2,1) xaxis2,yaxis2 \]
 
     >>> fig.add_scatter(y=[2, 1, 3], row=1, col=1) # doctest: +ELLIPSIS
     Figure(...)
@@ -226,8 +226,8 @@ def make_subplots(
     >>> fig = make_subplots(rows=2, shared_xaxes=True)
 
     This is the format of your plot grid:
-    [ (1,1) xaxis1,yaxis1 ]
-    [ (2,1) xaxis2,yaxis2 ]
+    \[ (1,1) xaxis1,yaxis1 \]
+    \[ (2,1) xaxis2,yaxis2 \]
 
     >>> fig.add_scatter(y=[2, 1, 3], row=1, col=1) # doctest: +ELLIPSIS
     Figure(...)
@@ -242,8 +242,8 @@ def make_subplots(
     ...                     [{'colspan': 2}, None]])
 
     This is the format of your plot grid:
-    [ (1,1) xaxis1,yaxis1 ]  [ (1,2) xaxis2,yaxis2 ]
-    [ (2,1) xaxis3,yaxis3           -              ]
+    \[ (1,1) xaxis1,yaxis1 ]  [ (1,2) xaxis2,yaxis2 \]
+    \[ (2,1) xaxis3,yaxis3           -              \]
 
     >>> fig.add_trace(go.Scatter(x=[1,2,3], y=[2,1,2]), row=1, col=1) # doctest: +ELLIPSIS
     Figure(...)
@@ -258,10 +258,10 @@ def make_subplots(
     >>> fig = make_subplots(insets=[{'cell': (1,1), 'l': 0.7, 'b': 0.3}])
 
     This is the format of your plot grid:
-    [ (1,1) xaxis1,yaxis1 ]
+    \[ (1,1) xaxis1,yaxis1 \]
 
     With insets:
-    [ xaxis2,yaxis2 ] over [ (1,1) xaxis1,yaxis1 ]
+    \[ xaxis2,yaxis2 \] over \[ (1,1) xaxis1,yaxis1 \]
 
     >>> fig.add_scatter(x=[1,2,3], y=[2,1,1]) # doctest: +ELLIPSIS
     Figure(...)
@@ -274,8 +274,8 @@ def make_subplots(
     >>> fig = make_subplots(rows=2, subplot_titles=('Plot 1','Plot 2'))
 
     This is the format of your plot grid:
-    [ (1,1) x1,y1 ]
-    [ (2,1) x2,y2 ]
+    \[ (1,1) x1,y1 \]
+    \[ (2,1) x2,y2 \]
 
     >>> fig.add_scatter(x=[1,2,3], y=[2,1,2], row=1, col=1) # doctest: +ELLIPSIS
     Figure(...)