|
1 | | -importre |
2 | | -fromdocutils.parsers.rstimportDirective |
| 1 | +""" |
| 2 | +Sphinx extension that generates the math symbol table documentation |
| 3 | +for Matplotlib. |
| 4 | +""" |
3 | 5 |
|
4 | | -frommatplotlibimport_mathtext,_mathtext_data |
| 6 | +from __future__importannotations |
| 7 | +frompathlibimportPath |
| 8 | +fromsphinx.util.docutilsimportSphinxDirective |
5 | 9 |
|
6 | | -bb_pattern=re.compile("Bbb[A-Z]") |
7 | | -scr_pattern=re.compile("scr[a-zA-Z]") |
8 | | -frak_pattern=re.compile("frak[A-Z]") |
| 10 | +# This import ensures access to Matplotlib’s mathtext internals |
| 11 | +frommatplotlibimport_mathtext |
9 | 12 |
|
10 | | -symbols= [ |
11 | | - ["Lower-case Greek", |
12 | | -4, |
13 | | - (r"\alpha",r"\beta",r"\gamma",r"\chi",r"\delta",r"\epsilon", |
14 | | -r"\eta",r"\iota",r"\kappa",r"\lambda",r"\mu",r"\nu",r"\omega", |
15 | | -r"\phi",r"\pi",r"\psi",r"\rho",r"\sigma",r"\tau",r"\theta", |
16 | | -r"\upsilon",r"\xi",r"\zeta",r"\digamma",r"\varepsilon",r"\varkappa", |
17 | | -r"\varphi",r"\varpi",r"\varrho",r"\varsigma",r"\vartheta")], |
18 | | - ["Upper-case Greek", |
19 | | -4, |
20 | | - (r"\Delta",r"\Gamma",r"\Lambda",r"\Omega",r"\Phi",r"\Pi",r"\Psi", |
21 | | -r"\Sigma",r"\Theta",r"\Upsilon",r"\Xi")], |
22 | | - ["Hebrew", |
23 | | -6, |
24 | | - (r"\aleph",r"\beth",r"\gimel",r"\daleth")], |
25 | | - ["Latin named characters", |
26 | | -6, |
27 | | -r"""\aa \AA \ae \AE \oe \OE \O \o \thorn \Thorn \ss \eth \dh \DH""".split()], |
28 | | - ["Delimiters", |
29 | | -5, |
30 | | -_mathtext.Parser._delims], |
31 | | - ["Big symbols", |
32 | | -5, |
33 | | -_mathtext.Parser._overunder_symbols|_mathtext.Parser._dropsub_symbols], |
34 | | - ["Standard function names", |
35 | | -5, |
36 | | - {fr"\{fn}"forfnin_mathtext.Parser._function_names}], |
37 | | - ["Binary operation symbols", |
38 | | -4, |
39 | | -_mathtext.Parser._binary_operators], |
40 | | - ["Relation symbols", |
41 | | -4, |
42 | | -_mathtext.Parser._relation_symbols], |
43 | | - ["Arrow symbols", |
44 | | -4, |
45 | | -_mathtext.Parser._arrow_symbols], |
46 | | - ["Dot symbols", |
47 | | -4, |
48 | | -r"""\cdots \vdots \ldots \ddots \adots \Colon \therefore \because""".split()], |
49 | | - ["Black-board characters", |
50 | | -6, |
51 | | - [fr"\{symbol}"forsymbolin_mathtext_data.tex2uni |
52 | | -ifre.match(bb_pattern,symbol)]], |
53 | | - ["Script characters", |
54 | | -6, |
55 | | - [fr"\{symbol}"forsymbolin_mathtext_data.tex2uni |
56 | | -ifre.match(scr_pattern,symbol)]], |
57 | | - ["Fraktur characters", |
58 | | -6, |
59 | | - [fr"\{symbol}"forsymbolin_mathtext_data.tex2uni |
60 | | -ifre.match(frak_pattern,symbol)]], |
61 | | - ["Miscellaneous symbols", |
62 | | -4, |
63 | | -r"""\neg \infty \forall \wp \exists \bigstar \angle \partial |
64 | | - \nexists \measuredangle \emptyset \sphericalangle \clubsuit |
65 | | - \varnothing \complement \diamondsuit \imath \Finv \triangledown |
66 | | - \heartsuit \jmath \Game \spadesuit \ell \hbar \vartriangle |
67 | | - \hslash \blacksquare \blacktriangle \sharp \increment |
68 | | - \prime \blacktriangledown \Im \flat \backprime \Re \natural |
69 | | - \circledS \P \copyright \circledR \S \yen \checkmark \$ |
70 | | - \cent \triangle \QED \sinewave \dag \ddag \perthousand \ac |
71 | | - \lambdabar \L \l \degree \danger \maltese \clubsuitopen |
72 | | - \i \hermitmatrix \sterling \nabla \mho""".split()], |
73 | | -] |
74 | 13 |
|
75 | | - |
76 | | -defrun(state_machine): |
77 | | - |
78 | | -defrender_symbol(sym,ignore_variant=False): |
79 | | -ifignore_variantandsymnotin (r"\varnothing",r"\varlrtriangle"): |
80 | | -sym=sym.replace(r"\var","\\") |
81 | | -ifsym.startswith("\\"): |
82 | | -sym=sym.lstrip("\\") |
83 | | -ifsymnotin (_mathtext.Parser._overunder_functions| |
84 | | -_mathtext.Parser._function_names): |
85 | | -sym=chr(_mathtext_data.tex2uni[sym]) |
86 | | -returnf'\\{sym}'ifsymin ('\\','|','+','-','*')elsesym |
87 | | - |
88 | | -lines= [] |
89 | | -forcategory,columns,symsinsymbols: |
90 | | -syms=sorted(syms, |
91 | | -# Sort by Unicode and place variants immediately |
92 | | -# after standard versions. |
93 | | -key=lambdasym: (render_symbol(sym,ignore_variant=True), |
94 | | -sym.startswith(r"\var")), |
95 | | -reverse=(category=="Hebrew"))# Hebrew is rtl |
96 | | -rendered_syms= [f"{render_symbol(sym)} ``{sym}``"forsyminsyms] |
97 | | -columns=min(columns,len(syms)) |
98 | | -lines.append("**%s**"%category) |
99 | | -lines.append('') |
100 | | -max_width=max(map(len,rendered_syms)) |
101 | | -header= (('='*max_width)+' ')*columns |
102 | | -lines.append(header.rstrip()) |
103 | | -forpartinrange(0,len(rendered_syms),columns): |
104 | | -row=" ".join( |
105 | | -sym.rjust(max_width)forsyminrendered_syms[part:part+columns]) |
106 | | -lines.append(row) |
107 | | -lines.append(header.rstrip()) |
108 | | -lines.append('') |
109 | | - |
110 | | -state_machine.insert_input(lines,"Symbol table") |
111 | | -return [] |
112 | | - |
113 | | - |
114 | | -classMathSymbolTableDirective(Directive): |
115 | | -has_content=False |
116 | | -required_arguments=0 |
117 | | -optional_arguments=0 |
118 | | -final_argument_whitespace=False |
119 | | -option_spec= {} |
| 14 | +classMathSymbolTableDirective(SphinxDirective): |
| 15 | +""" |
| 16 | + Generate tables of math symbols grouped by category. |
| 17 | + """ |
120 | 18 |
|
121 | 19 | defrun(self): |
122 | | -returnrun(self.state_machine) |
| 20 | +lines= [] |
| 21 | +symbols=self._get_symbols() |
| 22 | + |
| 23 | +forcategory,columns,symsinsymbols: |
| 24 | +# Sort symbols for consistent order |
| 25 | +syms=sorted( |
| 26 | +syms, |
| 27 | +key=lambdasym: ( |
| 28 | +self._render_symbol(sym,ignore_variant=True), |
| 29 | +sym.startswith(r"\var"), |
| 30 | + ), |
| 31 | +reverse=(category=="Hebrew"),# RTL for Hebrew |
| 32 | + ) |
| 33 | + |
| 34 | +# Dynamically adjust number of columns |
| 35 | +iflen(syms)<=10: |
| 36 | +columns=2 |
| 37 | +eliflen(syms)<=20: |
| 38 | +columns=3 |
| 39 | +eliflen(syms)<=40: |
| 40 | +columns=4 |
| 41 | +else: |
| 42 | +columns=5 |
| 43 | + |
| 44 | +rendered_syms= [ |
| 45 | +f"{self._render_symbol(sym)} `{sym}`"forsyminsyms |
| 46 | + ] |
| 47 | +columns=min(columns,len(syms)) |
| 48 | +lines.append(f"**{category}**\n") |
| 49 | +lines.append(self._make_table(rendered_syms,columns)) |
| 50 | +lines.append("\n") |
| 51 | + |
| 52 | +fromdocutilsimportnodes |
| 53 | +node=nodes.paragraph() |
| 54 | +self.state.nested_parse(lines,0,node) |
| 55 | +return [node] |
| 56 | + |
| 57 | +# ------------------------------------------------------------------ |
| 58 | +# Helper methods |
| 59 | +# ------------------------------------------------------------------ |
| 60 | + |
| 61 | +def_get_symbols(self): |
| 62 | +""" |
| 63 | + Returns the math symbols categorized for documentation. |
| 64 | + """ |
| 65 | +categories=_mathtext._get_sphinx_symbol_table() |
| 66 | +returncategories |
| 67 | + |
| 68 | +def_render_symbol(self,sym,ignore_variant=False): |
| 69 | +""" |
| 70 | + Renders a math symbol as HTML or LaTeX representation for docs. |
| 71 | + """ |
| 72 | +try: |
| 73 | +html=_mathtext.math_to_image( |
| 74 | +f"${sym}$","png",Path("/tmp/test.png"),dpi=120 |
| 75 | + ) |
| 76 | +returnf":math:`{sym}`" |
| 77 | +exceptException: |
| 78 | +returnsym |
| 79 | + |
| 80 | +def_make_table(self,items,ncol): |
| 81 | +""" |
| 82 | + Build a simple RST table layout from the list of symbols. |
| 83 | + """ |
| 84 | +nrow= (len(items)+ncol-1)//ncol |
| 85 | +rows= [] |
| 86 | +foriinrange(nrow): |
| 87 | +row=items[i::nrow] |
| 88 | +rows.append(" | ".join(row)) |
| 89 | +table="\n".join(rows) |
| 90 | +returntable |
123 | 91 |
|
124 | 92 |
|
125 | 93 | defsetup(app): |
126 | | -app.add_directive("math_symbol_table",MathSymbolTableDirective) |
127 | | - |
128 | | -metadata= {'parallel_read_safe':True,'parallel_write_safe':True} |
129 | | -returnmetadata |
130 | | - |
131 | | - |
132 | | -if__name__=="__main__": |
133 | | -# Do some verification of the tables |
134 | | - |
135 | | -print("SYMBOLS NOT IN STIX:") |
136 | | -all_symbols= {} |
137 | | -forcategory,columns,symsinsymbols: |
138 | | -ifcategory=="Standard Function Names": |
139 | | -continue |
140 | | -forsyminsyms: |
141 | | -iflen(sym)>1: |
142 | | -all_symbols[sym[1:]]=None |
143 | | -ifsym[1:]notin_mathtext_data.tex2uni: |
144 | | -print(sym) |
145 | | - |
146 | | -# Add accents |
147 | | -all_symbols.update({v[1:]:kfork,vin_mathtext.Parser._accent_map.items()}) |
148 | | -all_symbols.update({v:vforvin_mathtext.Parser._wide_accents}) |
149 | | -print("SYMBOLS NOT IN TABLE:") |
150 | | -forsym,valin_mathtext_data.tex2uni.items(): |
151 | | -ifsymnotinall_symbols: |
152 | | -print(f"{sym} ={chr(val)}") |
| 94 | +""" |
| 95 | + Register the Sphinx extension. |
| 96 | + """ |
| 97 | +app.add_directive("mathsymboltable",MathSymbolTableDirective) |
| 98 | +return { |
| 99 | +"version":"1.0", |
| 100 | +"parallel_read_safe":True, |
| 101 | +"parallel_write_safe":True, |
| 102 | + } |