openscad-docsgen 2.0.43__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2021 Revar Desmera
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,326 @@
1
+ Metadata-Version: 2.1
2
+ Name: openscad_docsgen
3
+ Version: 2.0.43
4
+ Summary: A processor to generate Markdown code documentation with images from OpenSCAD source comments.
5
+ Author-email: Revar Desmera <revarbat@gmail.com>
6
+ Maintainer-email: Revar Desmera <revarbat@gmail.com>
7
+ Project-URL: Homepage, https://github.com/belfryscad/openscad_docsgen
8
+ Project-URL: Repository, https://github.com/belfryscad/openscad_docsgen
9
+ Project-URL: Bug Tracker, https://github.com/belfryscad/openscad_docsgen/issues
10
+ Project-URL: Releases, https://github.com/belfryscad/openscad_docsgen/releases
11
+ Project-URL: Usage, https://github.com/belfryscad/openscad_docsgen/README.rst
12
+ Project-URL: Documentation, https://github.com/belfryscad/openscad_docsgen/WRITING_DOCS.md
13
+ Keywords: openscad,documentation generation,docs generation,docsgen
14
+ Classifier: Development Status :: 5 - Production/Stable
15
+ Classifier: Environment :: Console
16
+ Classifier: Intended Audience :: Developers
17
+ Classifier: Intended Audience :: Manufacturing
18
+ Classifier: License :: OSI Approved :: MIT License
19
+ Classifier: Operating System :: MacOS :: MacOS X
20
+ Classifier: Operating System :: Microsoft :: Windows
21
+ Classifier: Operating System :: POSIX
22
+ Classifier: Programming Language :: Python :: 3
23
+ Classifier: Topic :: Artistic Software
24
+ Classifier: Topic :: Multimedia :: Graphics :: 3D Modeling
25
+ Classifier: Topic :: Multimedia :: Graphics :: 3D Rendering
26
+ Classifier: Topic :: Software Development :: Libraries
27
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
28
+ Requires-Python: >=3.7
29
+ Description-Content-Type: text/x-rst
30
+ License-File: LICENSE
31
+ Requires-Dist: pillow>=10.3.0
32
+ Requires-Dist: PyYAML>=6.0
33
+ Requires-Dist: openscad_runner>=1.1.1
34
+
35
+ ################################
36
+ OpenSCAD Documentation Generator
37
+ ################################
38
+
39
+ This package generates wiki-ready GitHub flavored markdown documentation pages from in-line source
40
+ code comments. This is similar to Doxygen or JavaDoc, but designed for use with OpenSCAD code.
41
+ Example images can be generated automatically from short example scripts.
42
+
43
+ Documentation about how to add documentation comments to OpenSCAD code can be found at
44
+ `https://github.com/revarbat/openscad_docsgen/blob/main/WRITING_DOCS.md`
45
+
46
+
47
+ Installing openscad-docsgen
48
+ ---------------------------
49
+
50
+ The easiest way to install this is to use pip::
51
+
52
+ % pip3 install openscad_docsgen
53
+
54
+ To install directly from these sources, you can instead do::
55
+
56
+ % python3 setup.py build install
57
+
58
+
59
+ Using openscad-docsgen
60
+ ----------------------
61
+
62
+ The simplest way to generate documentation is::
63
+
64
+ % openscad-docsgen -m *.scad
65
+
66
+ Which will read all of .scad files in the current directory, and writes out documentation
67
+ for each .scad file to the ``./docs/`` dir. To write out to a different directory, use
68
+ the ``-D`` argument::
69
+
70
+ % openscad-docsgen -D wikidir -m *.scad
71
+
72
+ To write out an alphabetical function/module index markdown file, use the ``-i`` flag::
73
+
74
+ % openscad-docsgen -i *.scad
75
+
76
+ To write out a Table of Contents markdown file, use the ``-t`` flag::
77
+
78
+ % openscad-docsgen -t *.scad
79
+
80
+ To write out a CheatSheet markdown file, use the ``-c`` flag. In addition, you can
81
+ specify the project name shown in the CheatSheet with the ``-P PROJECTNAME`` argument::
82
+
83
+ % openscad-docsgen -c -P "My Foobar Library" *.scad
84
+
85
+ A Topics index file can be generated by passing the ``-I`` flag::
86
+
87
+ % openscad-docsgen -I *.scad
88
+
89
+ You can just test for script errors more quickly with the ``-T`` flag (for test-only)::
90
+
91
+ % openscad-docsgen -m -T *.scad
92
+
93
+ By default, the target output profile is to generate documentation for a GitHub Wiki.
94
+ You can output for a more generic Wiki with ``-p wiki``::
95
+
96
+ % openscad-docsgen -ticmI -p wiki *.scad
97
+
98
+
99
+ Docsgen Configuration File
100
+ --------------------------
101
+ You can also make more persistent configurations by putting a `.openscad_docsgen_rc` file in the
102
+ directory you will be running openscad-docsgen from. It can look something like this::
103
+
104
+ DocsDirectory: WikiDir/
105
+ TargetProfile: githubwiki
106
+ ProjectName: The Foobar Project
107
+ GeneratedDocs: Files, ToC, Index, Topics, CheatSheet
108
+ SidebarHeader:
109
+ ## Indices
110
+ .
111
+ SidebarMiddle:
112
+ [Tutorials](Tutorials)
113
+ IgnoreFiles:
114
+ foo.scad
115
+ std.scad
116
+ version.scad
117
+ tmp_*.scad
118
+ PrioritizeFiles:
119
+ First.scad
120
+ Second.scad
121
+ Third.scad
122
+ Fourth.scad
123
+ DefineHeader(BulletList): Side Effects
124
+ DefineHeader(Table;Headers=Anchor&nbsp;Name|Position): Extra Anchors
125
+
126
+ For an explanation of the syntax and the specific headers, see:
127
+ `https://github.com/revarbat/openscad_docsgen/blob/main/WRITING_DOCS.md`
128
+
129
+ Using openscad-mdimggen
130
+ -----------------------
131
+ If you have MarkDown based files that you would like to generate images for, you can use the
132
+ `openscad_mdimggen` command. It can take the following arguments::
133
+
134
+ -h, --help Show help message and exit
135
+ -D DOCS_DIR, --docs-dir DOCS_DIR
136
+ The directory to put generated documentation in.
137
+ -P FILE_PREFIX, --file-prefix FILE_PREFIX
138
+ The prefix to put in front of each output markdown file.
139
+ -T, --test-only If given, don't generate images, but do try executing the scripts.
140
+ -I IMAGE_ROOT, --image_root IMAGE_ROOT
141
+ The directory to put generated images in.
142
+ -f, --force If given, force regeneration of images.
143
+ -a, --png-animation If given, animations are created using animated PNGs instead of GIFs.
144
+
145
+ What `openscad-mdimggen` will do is read the input MarkDown file and look for fenced scripts of
146
+ OpenSCAD code, that starts with a line of the form::
147
+
148
+ ```openscad-METADATA
149
+
150
+ It will copy all non-script lines to the output markdown file, and run OpenSCAD for each of the
151
+ found fenced scripts, inserting the generated image into the output MarkDown file after the script block.
152
+ The METADATA for each script will define the viewpoint and other info for the given generated image.
153
+ This METADATA takes the form of a set of semi-colon separated options that can be any of the following:
154
+
155
+ - ``NORENDER``: Don't generate an image for this example, but show the example text.
156
+ - ``ImgOnly``: Generate and show the image, but hide the text of the script.
157
+ - ``Hide``: Generate, but don't show script or image. This can be used to generate images to be manually displayed in markdown text blocks.
158
+ - ``2D``: Orient camera in a top-down view for showing 2D objects.
159
+ - ``3D``: Orient camera in an oblique view for showing 3D objects.
160
+ - ``VPT=[10,20,30]`` Force the viewpoint translation `$vpt` to `[10,20,30]`.
161
+ - ``VPR=[55,0,600]`` Force the viewpoint rotation `$vpr` to `[55,0,60]`.
162
+ - ``VPD=440``: Force viewpoint distance `$vpd` to 440.
163
+ - ``VPF=22.5``: Force field of view angle `$vpf` to 22.5.
164
+ - ``Spin``: Animate camera orbit around the `[0,1,1]` axis to display all sides of an object.
165
+ - ``FlatSpin``: Animate camera orbit around the Z axis, above the XY plane.
166
+ - ``Anim``: Make an animation where `$t` varies from `0.0` to almost `1.0`.
167
+ - ``FrameMS=250``: Sets the number of milliseconds per frame for spins and animation.
168
+ - ``FPS=8``: Sets the number of frames per second for spins and animation.
169
+ - ``Frames=36``: Number of animation frames to make.
170
+ - ``Small``: Make the image small sized.
171
+ - ``Med``: Make the image medium sized.
172
+ - ``Big``: Make the image big sized.
173
+ - ``Huge``: Make the image huge sized.
174
+ - ``Size=880x640``: Make the image 880 by 640 pixels in size.
175
+ - ``Render``: Force full rendering from OpenSCAD, instead of the normal preview.
176
+ - ``Edges``: Highlight face edges.
177
+ - ``NoAxes``: Hides the axes and scales.
178
+ - ``NoScales``: Hides the scale numbers along the axes.
179
+ - ``ColorScheme``: Generate the image using a specific color scheme
180
+ - Usage: ``ColorScheme=<color scheme name>`` (e.g. ``ColorScheme=BeforeDawn``)
181
+ - Default color scheme: ``Cornfield``
182
+ - Predefined color schemes: ``Cornfield``, ``Metallic``, ``Sunset``, ``Starnight``, ``BeforeDawn``, ``Nature``, ``DeepOcean``, ``Solarized``, ``Tomorrow``, ``Tomorrow Night``, ``Monotone``
183
+ - Color schemes defined as a [Read-only Resource](https://github.com/openscad/openscad/wiki/Path-locations#read-only-resources) or [User Resource](https://github.com/openscad/openscad/wiki/Path-locations#user-resources) are also supported.
184
+
185
+ For example::
186
+
187
+ ```openscad-FlatSpin;VPD=500
188
+ prismoid([60,40], [40,20], h=40, offset=[10,10]);
189
+ ```
190
+
191
+ Will generate an animated flat spin of the prismoid at a viewing distance of 500. While::
192
+
193
+ ```openscad-3D;Big
194
+ prismoid([60,40], [40,20], h=40, offset=[10,10]);
195
+ ```
196
+
197
+ Will generate a still image of the same prismoid, but at a bigger image size.
198
+
199
+ MDImgGen Configuration File
200
+ ---------------------------
201
+ You can store defaults for ``openscad_mdimggen`` in the ``.openscad_mdimggen_rc`` file like this::
202
+
203
+ docs_dir: "BOSL2.wiki"
204
+ image_root: "images/tutorials"
205
+ file_prefix: "Tutorial-"
206
+ source_files: "tutorials/*.md"
207
+ png_animations: true
208
+
209
+
210
+ External Calling
211
+ ----------------
212
+ Here's an example of how to use this library, to get the parsed documentation data::
213
+
214
+ import openscad_docsgen as docsgen
215
+ from glob import glob
216
+ from pprint import pprint
217
+ dgp = docsgen.DocsGenParser(quiet=True)
218
+ dgp.parse_files(glob("*.scad"))
219
+ for name in dgp.get_indexed_names():
220
+ data = dgp.get_indexed_data(name)
221
+ pprint(name)
222
+ pprint(data["description"])
223
+
224
+ The data for an OpenSCAD function, module, or constant generally looks like::
225
+
226
+ {
227
+ 'name': 'Function&Module', // Could also be 'Function', 'Module', or 'Constant'
228
+ 'subtitle': 'line_of()',
229
+ 'body': [],
230
+ 'file': 'distributors.scad',
231
+ 'line': 43,
232
+ 'aliases': ['linear_spread()'],
233
+ 'topics': ['Distributors'],
234
+ 'usages': [
235
+ {
236
+ 'subtitle': 'Spread `n` copies by a given spacing',
237
+ 'body': ['line_of(spacing, <n>, <p1=>) ...']
238
+ },
239
+ {
240
+ 'subtitle': 'Spread copies every given spacing along the line',
241
+ 'body': ['line_of(spacing, <l=>, <p1=>) ...']
242
+ },
243
+ {
244
+ 'subtitle': 'Spread `n` copies along the length of the line',
245
+ 'body': ['line_of(<n=>, <l=>, <p1=>) ...']
246
+ },
247
+ {
248
+ 'subtitle': 'Spread `n` copies along the line from `p1` to `p2`',
249
+ 'body': ['line_of(<n=>, <p1=>, <p2=>) ...']
250
+ },
251
+ {
252
+ 'subtitle': 'Spread copies every given spacing, centered along the line from `p1` to `p2`',
253
+ 'body': ['line_of(<spacing>, <p1=>, <p2=>) ...']
254
+ },
255
+ {
256
+ 'subtitle': 'As a function',
257
+ 'body': [
258
+ 'pts = line_of(<spacing>, <n>, <p1=>);',
259
+ 'pts = line_of(<spacing>, <l=>, <p1=>);',
260
+ 'pts = line_of(<n=>, <l=>, <p1=>);',
261
+ 'pts = line_of(<n=>, <p1=>, <p2=>);',
262
+ 'pts = line_of(<spacing>, <p1=>, <p2=>);'
263
+ ]
264
+ }
265
+ ],
266
+ 'description': [
267
+ 'When called as a function, returns a list of points at evenly spread positions along a line.',
268
+ 'When called as a module, copies `children()` at one or more evenly spread positions along a line.',
269
+ 'By default, the line will be centered at the origin, unless the starting point `p1` is given.',
270
+ 'The line will be pointed towards `RIGHT` (X+) unless otherwise given as a vector in `l`,',
271
+ '`spacing`, or `p1`/`p2`.',
272
+ ],
273
+ 'arguments': [
274
+ 'spacing = The vector giving both the direction and spacing distance between each set of copies.',
275
+ 'n = Number of copies to distribute along the line. (Default: 2)',
276
+ '---',
277
+ 'l = Either the scalar length of the line, or a vector giving both the direction and length of the line.',
278
+ 'p1 = If given, specifies the starting point of the line.',
279
+ 'p2 = If given with `p1`, specifies the ending point of line, and indirectly calculates the line length.'
280
+ ],
281
+ 'see_also': ['xcopies()', 'ycopies()'],
282
+ 'examples': [
283
+ ['line_of(10) sphere(d=1);'],
284
+ ['line_of(10, n=5) sphere(d=1);'],
285
+ ['line_of([10,5], n=5) sphere(d=1);'],
286
+ ['line_of(spacing=10, n=6) sphere(d=1);'],
287
+ ['line_of(spacing=[10,5], n=6) sphere(d=1);'],
288
+ ['line_of(spacing=10, l=50) sphere(d=1);'],
289
+ ['line_of(spacing=10, l=[50,30]) sphere(d=1);'],
290
+ ['line_of(spacing=[10,5], l=50) sphere(d=1);'],
291
+ ['line_of(l=50, n=4) sphere(d=1);'],
292
+ ['line_of(l=[50,-30], n=4) sphere(d=1);'],
293
+ [
294
+ 'line_of(p1=[0,0,0], p2=[5,5,20], n=6) '
295
+ 'cube(size=[3,2,1],center=true);'
296
+ ],
297
+ [
298
+ 'line_of(p1=[0,0,0], p2=[5,5,20], spacing=6) '
299
+ 'cube(size=[3,2,1],center=true);'
300
+ ],
301
+ [
302
+ 'line_of(l=20, n=3) {',
303
+ ' cube(size=[1,3,1],center=true);',
304
+ ' cube(size=[3,1,1],center=true);',
305
+ '}'
306
+ ],
307
+ [
308
+ 'pts = line_of([10,5],n=5);',
309
+ 'move_copies(pts) circle(d=2);'
310
+ ]
311
+ ],
312
+ 'children': [
313
+ {
314
+ 'name': 'Side Effects',
315
+ 'subtitle': '',
316
+ 'body': [
317
+ '`$pos` is set to the relative centerpoint of each child copy.',
318
+ '`$idx` is set to the index number of each child being copied.'
319
+ ],
320
+ 'file': 'distributors.scad',
321
+ 'line': 88
322
+ }
323
+ ]
324
+ }
325
+
326
+
@@ -0,0 +1,292 @@
1
+ ################################
2
+ OpenSCAD Documentation Generator
3
+ ################################
4
+
5
+ This package generates wiki-ready GitHub flavored markdown documentation pages from in-line source
6
+ code comments. This is similar to Doxygen or JavaDoc, but designed for use with OpenSCAD code.
7
+ Example images can be generated automatically from short example scripts.
8
+
9
+ Documentation about how to add documentation comments to OpenSCAD code can be found at
10
+ `https://github.com/revarbat/openscad_docsgen/blob/main/WRITING_DOCS.md`
11
+
12
+
13
+ Installing openscad-docsgen
14
+ ---------------------------
15
+
16
+ The easiest way to install this is to use pip::
17
+
18
+ % pip3 install openscad_docsgen
19
+
20
+ To install directly from these sources, you can instead do::
21
+
22
+ % python3 setup.py build install
23
+
24
+
25
+ Using openscad-docsgen
26
+ ----------------------
27
+
28
+ The simplest way to generate documentation is::
29
+
30
+ % openscad-docsgen -m *.scad
31
+
32
+ Which will read all of .scad files in the current directory, and writes out documentation
33
+ for each .scad file to the ``./docs/`` dir. To write out to a different directory, use
34
+ the ``-D`` argument::
35
+
36
+ % openscad-docsgen -D wikidir -m *.scad
37
+
38
+ To write out an alphabetical function/module index markdown file, use the ``-i`` flag::
39
+
40
+ % openscad-docsgen -i *.scad
41
+
42
+ To write out a Table of Contents markdown file, use the ``-t`` flag::
43
+
44
+ % openscad-docsgen -t *.scad
45
+
46
+ To write out a CheatSheet markdown file, use the ``-c`` flag. In addition, you can
47
+ specify the project name shown in the CheatSheet with the ``-P PROJECTNAME`` argument::
48
+
49
+ % openscad-docsgen -c -P "My Foobar Library" *.scad
50
+
51
+ A Topics index file can be generated by passing the ``-I`` flag::
52
+
53
+ % openscad-docsgen -I *.scad
54
+
55
+ You can just test for script errors more quickly with the ``-T`` flag (for test-only)::
56
+
57
+ % openscad-docsgen -m -T *.scad
58
+
59
+ By default, the target output profile is to generate documentation for a GitHub Wiki.
60
+ You can output for a more generic Wiki with ``-p wiki``::
61
+
62
+ % openscad-docsgen -ticmI -p wiki *.scad
63
+
64
+
65
+ Docsgen Configuration File
66
+ --------------------------
67
+ You can also make more persistent configurations by putting a `.openscad_docsgen_rc` file in the
68
+ directory you will be running openscad-docsgen from. It can look something like this::
69
+
70
+ DocsDirectory: WikiDir/
71
+ TargetProfile: githubwiki
72
+ ProjectName: The Foobar Project
73
+ GeneratedDocs: Files, ToC, Index, Topics, CheatSheet
74
+ SidebarHeader:
75
+ ## Indices
76
+ .
77
+ SidebarMiddle:
78
+ [Tutorials](Tutorials)
79
+ IgnoreFiles:
80
+ foo.scad
81
+ std.scad
82
+ version.scad
83
+ tmp_*.scad
84
+ PrioritizeFiles:
85
+ First.scad
86
+ Second.scad
87
+ Third.scad
88
+ Fourth.scad
89
+ DefineHeader(BulletList): Side Effects
90
+ DefineHeader(Table;Headers=Anchor&nbsp;Name|Position): Extra Anchors
91
+
92
+ For an explanation of the syntax and the specific headers, see:
93
+ `https://github.com/revarbat/openscad_docsgen/blob/main/WRITING_DOCS.md`
94
+
95
+ Using openscad-mdimggen
96
+ -----------------------
97
+ If you have MarkDown based files that you would like to generate images for, you can use the
98
+ `openscad_mdimggen` command. It can take the following arguments::
99
+
100
+ -h, --help Show help message and exit
101
+ -D DOCS_DIR, --docs-dir DOCS_DIR
102
+ The directory to put generated documentation in.
103
+ -P FILE_PREFIX, --file-prefix FILE_PREFIX
104
+ The prefix to put in front of each output markdown file.
105
+ -T, --test-only If given, don't generate images, but do try executing the scripts.
106
+ -I IMAGE_ROOT, --image_root IMAGE_ROOT
107
+ The directory to put generated images in.
108
+ -f, --force If given, force regeneration of images.
109
+ -a, --png-animation If given, animations are created using animated PNGs instead of GIFs.
110
+
111
+ What `openscad-mdimggen` will do is read the input MarkDown file and look for fenced scripts of
112
+ OpenSCAD code, that starts with a line of the form::
113
+
114
+ ```openscad-METADATA
115
+
116
+ It will copy all non-script lines to the output markdown file, and run OpenSCAD for each of the
117
+ found fenced scripts, inserting the generated image into the output MarkDown file after the script block.
118
+ The METADATA for each script will define the viewpoint and other info for the given generated image.
119
+ This METADATA takes the form of a set of semi-colon separated options that can be any of the following:
120
+
121
+ - ``NORENDER``: Don't generate an image for this example, but show the example text.
122
+ - ``ImgOnly``: Generate and show the image, but hide the text of the script.
123
+ - ``Hide``: Generate, but don't show script or image. This can be used to generate images to be manually displayed in markdown text blocks.
124
+ - ``2D``: Orient camera in a top-down view for showing 2D objects.
125
+ - ``3D``: Orient camera in an oblique view for showing 3D objects.
126
+ - ``VPT=[10,20,30]`` Force the viewpoint translation `$vpt` to `[10,20,30]`.
127
+ - ``VPR=[55,0,600]`` Force the viewpoint rotation `$vpr` to `[55,0,60]`.
128
+ - ``VPD=440``: Force viewpoint distance `$vpd` to 440.
129
+ - ``VPF=22.5``: Force field of view angle `$vpf` to 22.5.
130
+ - ``Spin``: Animate camera orbit around the `[0,1,1]` axis to display all sides of an object.
131
+ - ``FlatSpin``: Animate camera orbit around the Z axis, above the XY plane.
132
+ - ``Anim``: Make an animation where `$t` varies from `0.0` to almost `1.0`.
133
+ - ``FrameMS=250``: Sets the number of milliseconds per frame for spins and animation.
134
+ - ``FPS=8``: Sets the number of frames per second for spins and animation.
135
+ - ``Frames=36``: Number of animation frames to make.
136
+ - ``Small``: Make the image small sized.
137
+ - ``Med``: Make the image medium sized.
138
+ - ``Big``: Make the image big sized.
139
+ - ``Huge``: Make the image huge sized.
140
+ - ``Size=880x640``: Make the image 880 by 640 pixels in size.
141
+ - ``Render``: Force full rendering from OpenSCAD, instead of the normal preview.
142
+ - ``Edges``: Highlight face edges.
143
+ - ``NoAxes``: Hides the axes and scales.
144
+ - ``NoScales``: Hides the scale numbers along the axes.
145
+ - ``ColorScheme``: Generate the image using a specific color scheme
146
+ - Usage: ``ColorScheme=<color scheme name>`` (e.g. ``ColorScheme=BeforeDawn``)
147
+ - Default color scheme: ``Cornfield``
148
+ - Predefined color schemes: ``Cornfield``, ``Metallic``, ``Sunset``, ``Starnight``, ``BeforeDawn``, ``Nature``, ``DeepOcean``, ``Solarized``, ``Tomorrow``, ``Tomorrow Night``, ``Monotone``
149
+ - Color schemes defined as a [Read-only Resource](https://github.com/openscad/openscad/wiki/Path-locations#read-only-resources) or [User Resource](https://github.com/openscad/openscad/wiki/Path-locations#user-resources) are also supported.
150
+
151
+ For example::
152
+
153
+ ```openscad-FlatSpin;VPD=500
154
+ prismoid([60,40], [40,20], h=40, offset=[10,10]);
155
+ ```
156
+
157
+ Will generate an animated flat spin of the prismoid at a viewing distance of 500. While::
158
+
159
+ ```openscad-3D;Big
160
+ prismoid([60,40], [40,20], h=40, offset=[10,10]);
161
+ ```
162
+
163
+ Will generate a still image of the same prismoid, but at a bigger image size.
164
+
165
+ MDImgGen Configuration File
166
+ ---------------------------
167
+ You can store defaults for ``openscad_mdimggen`` in the ``.openscad_mdimggen_rc`` file like this::
168
+
169
+ docs_dir: "BOSL2.wiki"
170
+ image_root: "images/tutorials"
171
+ file_prefix: "Tutorial-"
172
+ source_files: "tutorials/*.md"
173
+ png_animations: true
174
+
175
+
176
+ External Calling
177
+ ----------------
178
+ Here's an example of how to use this library, to get the parsed documentation data::
179
+
180
+ import openscad_docsgen as docsgen
181
+ from glob import glob
182
+ from pprint import pprint
183
+ dgp = docsgen.DocsGenParser(quiet=True)
184
+ dgp.parse_files(glob("*.scad"))
185
+ for name in dgp.get_indexed_names():
186
+ data = dgp.get_indexed_data(name)
187
+ pprint(name)
188
+ pprint(data["description"])
189
+
190
+ The data for an OpenSCAD function, module, or constant generally looks like::
191
+
192
+ {
193
+ 'name': 'Function&Module', // Could also be 'Function', 'Module', or 'Constant'
194
+ 'subtitle': 'line_of()',
195
+ 'body': [],
196
+ 'file': 'distributors.scad',
197
+ 'line': 43,
198
+ 'aliases': ['linear_spread()'],
199
+ 'topics': ['Distributors'],
200
+ 'usages': [
201
+ {
202
+ 'subtitle': 'Spread `n` copies by a given spacing',
203
+ 'body': ['line_of(spacing, <n>, <p1=>) ...']
204
+ },
205
+ {
206
+ 'subtitle': 'Spread copies every given spacing along the line',
207
+ 'body': ['line_of(spacing, <l=>, <p1=>) ...']
208
+ },
209
+ {
210
+ 'subtitle': 'Spread `n` copies along the length of the line',
211
+ 'body': ['line_of(<n=>, <l=>, <p1=>) ...']
212
+ },
213
+ {
214
+ 'subtitle': 'Spread `n` copies along the line from `p1` to `p2`',
215
+ 'body': ['line_of(<n=>, <p1=>, <p2=>) ...']
216
+ },
217
+ {
218
+ 'subtitle': 'Spread copies every given spacing, centered along the line from `p1` to `p2`',
219
+ 'body': ['line_of(<spacing>, <p1=>, <p2=>) ...']
220
+ },
221
+ {
222
+ 'subtitle': 'As a function',
223
+ 'body': [
224
+ 'pts = line_of(<spacing>, <n>, <p1=>);',
225
+ 'pts = line_of(<spacing>, <l=>, <p1=>);',
226
+ 'pts = line_of(<n=>, <l=>, <p1=>);',
227
+ 'pts = line_of(<n=>, <p1=>, <p2=>);',
228
+ 'pts = line_of(<spacing>, <p1=>, <p2=>);'
229
+ ]
230
+ }
231
+ ],
232
+ 'description': [
233
+ 'When called as a function, returns a list of points at evenly spread positions along a line.',
234
+ 'When called as a module, copies `children()` at one or more evenly spread positions along a line.',
235
+ 'By default, the line will be centered at the origin, unless the starting point `p1` is given.',
236
+ 'The line will be pointed towards `RIGHT` (X+) unless otherwise given as a vector in `l`,',
237
+ '`spacing`, or `p1`/`p2`.',
238
+ ],
239
+ 'arguments': [
240
+ 'spacing = The vector giving both the direction and spacing distance between each set of copies.',
241
+ 'n = Number of copies to distribute along the line. (Default: 2)',
242
+ '---',
243
+ 'l = Either the scalar length of the line, or a vector giving both the direction and length of the line.',
244
+ 'p1 = If given, specifies the starting point of the line.',
245
+ 'p2 = If given with `p1`, specifies the ending point of line, and indirectly calculates the line length.'
246
+ ],
247
+ 'see_also': ['xcopies()', 'ycopies()'],
248
+ 'examples': [
249
+ ['line_of(10) sphere(d=1);'],
250
+ ['line_of(10, n=5) sphere(d=1);'],
251
+ ['line_of([10,5], n=5) sphere(d=1);'],
252
+ ['line_of(spacing=10, n=6) sphere(d=1);'],
253
+ ['line_of(spacing=[10,5], n=6) sphere(d=1);'],
254
+ ['line_of(spacing=10, l=50) sphere(d=1);'],
255
+ ['line_of(spacing=10, l=[50,30]) sphere(d=1);'],
256
+ ['line_of(spacing=[10,5], l=50) sphere(d=1);'],
257
+ ['line_of(l=50, n=4) sphere(d=1);'],
258
+ ['line_of(l=[50,-30], n=4) sphere(d=1);'],
259
+ [
260
+ 'line_of(p1=[0,0,0], p2=[5,5,20], n=6) '
261
+ 'cube(size=[3,2,1],center=true);'
262
+ ],
263
+ [
264
+ 'line_of(p1=[0,0,0], p2=[5,5,20], spacing=6) '
265
+ 'cube(size=[3,2,1],center=true);'
266
+ ],
267
+ [
268
+ 'line_of(l=20, n=3) {',
269
+ ' cube(size=[1,3,1],center=true);',
270
+ ' cube(size=[3,1,1],center=true);',
271
+ '}'
272
+ ],
273
+ [
274
+ 'pts = line_of([10,5],n=5);',
275
+ 'move_copies(pts) circle(d=2);'
276
+ ]
277
+ ],
278
+ 'children': [
279
+ {
280
+ 'name': 'Side Effects',
281
+ 'subtitle': '',
282
+ 'body': [
283
+ '`$pos` is set to the relative centerpoint of each child copy.',
284
+ '`$idx` is set to the index number of each child being copied.'
285
+ ],
286
+ 'file': 'distributors.scad',
287
+ 'line': 88
288
+ }
289
+ ]
290
+ }
291
+
292
+