From f9aa81e178faae5e3d349648e9c6ce82a78bd5da Mon Sep 17 00:00:00 2001 From: Garth Minette Date: Tue, 5 Jan 2021 01:20:01 -0800 Subject: [PATCH] Improved docs gen script for Returns:, Custom:, Includes:, Topics:, and positional/named args spits. --- WRITING_DOCS.md | 72 +++++++++++++-------- affine.scad | 66 ++++++++++++------- arrays.scad | 6 +- attachments.scad | 4 +- beziers.scad | 4 +- bottlecaps.scad | 4 +- common.scad | 6 +- constants.scad | 4 +- coords.scad | 6 +- cubetruss.scad | 55 ++++++++++------ debug.scad | 4 +- distributors.scad | 4 +- edges.scad | 4 +- geometry.scad | 6 +- hingesnaps.scad | 4 +- hull.scad | 8 +-- involute_gears.scad | 5 +- joiners.scad | 4 +- knurling.scad | 4 +- linear_bearings.scad | 4 +- masks.scad | 4 +- math.scad | 6 +- metric_screws.scad | 4 +- mutators.scad | 4 +- nema_steppers.scad | 4 +- partitions.scad | 4 +- paths.scad | 4 +- phillips_drive.scad | 4 +- polyhedra.scad | 4 +- primitives.scad | 4 +- quaternions.scad | 4 +- queues.scad | 8 +-- regions.scad | 6 +- rounding.scad | 4 +- screws.scad | 4 +- scripts/docs_gen.py | 149 +++++++++++++++++++++++++++++++++---------- shapes.scad | 4 +- shapes2d.scad | 4 +- skin.scad | 8 +-- sliders.scad | 4 +- stacks.scad | 8 +-- std.scad | 6 +- strings.scad | 6 +- structs.scad | 8 +-- threading.scad | 4 +- torx_drive.scad | 4 +- transforms.scad | 4 +- triangulation.scad | 4 +- turtle3d.scad | 4 +- vectors.scad | 6 +- version.scad | 6 +- vnf.scad | 8 +-- walls.scad | 4 +- wiring.scad | 4 +- 54 files changed, 312 insertions(+), 275 deletions(-) diff --git a/WRITING_DOCS.md b/WRITING_DOCS.md index 19ee8e1f..ca380296 100644 --- a/WRITING_DOCS.md +++ b/WRITING_DOCS.md @@ -24,6 +24,29 @@ LibFile blocks can be followed by multiple lines that can be added as markdown t // The end of the block is denoted by a line without a comment. ``` +## Includes: + +Include blocks contain code that all examples in the file should show and use. This is generally used for `include ` and `use ` commands. Indentation is important. Less than three spaces indent denotes the end of the block + +``` +// Includes: +// include +// use +``` + +## CommonCode: + +CommonCode blocks can be used to denote code that can be shared between all of the Figure and Example blocks in the file, without being shown itself. Indentation is important. Less than three spaces indent denotes the end of the block + +``` +// CommonCode: +// module text3d(text, h=0.01, size=3) { +// linear_extrude(height=h, convexity=10) { +// text(text=text, size=size, valign="center", halign="center"); +// } +// } +``` + ## Section: Section blocks can be followed by multiple lines that can be added as markdown text after the header. Indentation is important, as it denotes the end of block. @@ -48,19 +71,6 @@ Sections can also include Figures; images generated from code that is not shown // cube([100,10,30], center=true); ``` -## CommonCode: - -CommonCode blocks can be used to denote code that can be shared between all of the Figure and Example blocks in the file, without being shown itself. Indentation is important. Less than three spaces indent denotes the end of the block - -``` -// CommonCode: -// module text3d(text, h=0.01, size=3) { -// linear_extrude(height=h, convexity=10) { -// text(text=text, size=size, valign="center", halign="center"); -// } -// } -``` - ## Module:/Function:/Function&Module:/Constant: Module, Function, and Constant docs blocks all have a similar specific format. Most sub-blocks are optional, except the Module/Function/Constant line, and the Description block. @@ -71,9 +81,12 @@ Valid sub-blocks are: - `Usage: Optional Usage Title` - Optional. Multiple allowed. Followed by an indented block of usage patterns. Optional arguments should be in braces like `[opt]`. Alternate args should be separated by a vertical bar like `r|d`. - `Description:` - Can be single-line or a multi-line block of the description. - `Figure: Optional Figure Title` - Optional. Multiple allowed. Followed by a multi-line code block used to create a figure image. The code will not be shown. All figures will follow the Description block. -- `Arguments:` - Denotes start of an indented block of argument descriptions. Each line has the argument name, a space, an equals, another space, then the description for the argument all on one line. Like `arg = The argument description`. If you really need to explain an argument in longer form, explain it in the Description. +- `Returns:` - Can be single-line or a multi-line block, describing the return value of this function. +- `Custom: Foo` - Creates a text block labeled `Foo:` followed by the given multi-line block of text. +- `Arguments:` - Denotes start of an indented block of argument descriptions. Each line has the argument name, a space, an equals, another space, then the description for the argument all on one line. Like `arg = The argument description`. If you really need to explain an argument in longer form, explain it in the Description. If an argument line is just `---`, then the arguments table is split into two tables, with the positional arguments before the `---` and arguments that should always be passed by name after. - `Side Effects:` - Denotes the start of a block describing the side effects, such as `$special_var`s that are set. - `Extra Anchors:` - Denotes the start of an indented block of available non-standard named anchors for a part. +- `Topics: Topic1, Topic2, Topic2, etc.` - Lets you list topics related to this fuction or module. - `Example:` - Denotes the beginning of a multi-line example code block. - `Examples:` - Denotes the beginning of a block of examples, where each line will be shows as a separate example with a separate image if needed. @@ -83,7 +96,8 @@ The full set of optional example tags are: - `2D`: Orient camera in a top-down view for showing 2D objects. - `3D`: Orient camera in an oblique view for showing 3D objects. Used to force an Example sub-block to generate an image in Function and Constant blocks. -- `NORENDER`: Don't generate an image for this example. +- `NORENDER`: Don't generate an image for this example, but show the example text. +- `Hide`: Don't show example text or image. This can be used to generate images to be manually displayed in markdown text blocks. - `Small`: Make the image small sized. (The default) - `Med`: Make the image medium sized. - `Big`: Make the image big sized. @@ -105,11 +119,10 @@ Indentation is important, as it denotes the end of sub-block. // foo(foo, flee, flie, [qux]) // Description: Short description. // Description: -// A longer, multi-line description. -// All description blocks are added together. -// You _can_ use *markdown* notation as well. -// You can have paragraph breaks by having a -// line with just a period, like this: +// A longer, multi-line description. If multiple description blocks exist, +// they are all are added together. You can use most *markdown* notation +// as well. You can have paragraph breaks by having a line with just a +// period, like this: // . // You can end multi-line blocks by un-indenting the next // line, or by using a comment with no spaces like this: @@ -121,22 +134,29 @@ Indentation is important, as it denotes the end of sub-block. // cube([10,100,50], center=true); // cube([100,10,30], center=true); // +// Returns: A description of the return value. +// +// Custom: Custom Block Title +// Multi-line text to be shown in the custom block. +// // Arguments: -// foo = This is the description of the foo argument. All on one line. -// bar = This is the description of the bar argument. All on one line. -// baz = This is the description of the baz argument. All on one line. -// qux = This is the description of the qux argument. All on one line. -// flee = This is the description of the flee argument. All on one line. -// flie = This is the description of the flie argument. All on one line. +// foo = This is the description of the first positional argument, foo. All on one line. +// bar = This is the description of the second positional argument, bar. All on one line. +// baz = This is the description of the third positional argument, baz. All on one line. +// --- +// qux = This is the description of the named argument qux. All on one line. +// flee = This is the description of the named argument flee. All on one line. // Side Effects: // `$floo` gets set to the floo value. // Extra Anchors: // "blawb" = An anchor at the blawb point of the part, oriented upwards. // "fewble" = An anchor at the fewble connector of the part, oriented back yowards Y+. +// Topics: Fubar, Barbie, Bazil // Examples: Each line below gets its own example block and image. // foo(foo="a", bar="b"); // foo(foo="b", baz="c"); // Example: Multi-line example. +// --$vpr = [55,0,120]; // Lines starting with `--` aren't shown in docs example text. // lst = [ // "multi-line examples", // "are shown in one block", diff --git a/affine.scad b/affine.scad index dbedf1f5..71a1e816 100644 --- a/affine.scad +++ b/affine.scad @@ -1,16 +1,16 @@ ////////////////////////////////////////////////////////////////////// // LibFile: affine.scad // Matrix math and affine transformation matrices. -// To use, add the following lines to the beginning of your file: -// ``` -// use -// ``` +// Includes: +// include ////////////////////////////////////////////////////////////////////// // Section: Matrix Manipulation // Function: ident() +// Usage: +// mat = ident(n); // Description: Create an `n` by `n` identity matrix. // Arguments: // n = The size of the identity matrix square, `n` by `n`. @@ -18,6 +18,8 @@ function ident(n) = [for (i = [0:1:n-1]) [for (j = [0:1:n-1]) (i==j)?1:0]]; // Function: affine2d_to_3d() +// Usage: +// mat = affine2d_to_3d(m); // Description: Takes a 3x3 affine2d matrix and returns its 4x4 affine3d equivalent. function affine2d_to_3d(m) = concat( [for (r = [0:2]) @@ -35,11 +37,15 @@ function affine2d_to_3d(m) = concat( // Function: affine2d_identity() +// Usage: +// mat = affine2d_identify(); // Description: Create a 3x3 affine2d identity matrix. function affine2d_identity() = ident(3); // Function: affine2d_translate() +// Usage: +// mat = affine2d_translate(v); // Description: // Returns the 3x3 affine2d matrix to perform a 2D translation. // Arguments: @@ -52,6 +58,8 @@ function affine2d_translate(v) = [ // Function: affine2d_scale() +// Usage: +// mat = affine2d_scale(v); // Description: // Returns the 3x3 affine2d matrix to perform a 2D scaling transformation. // Arguments: @@ -64,6 +72,8 @@ function affine2d_scale(v) = [ // Function: affine2d_zrot() +// Usage: +// mat = affine2d_zrot(ang); // Description: // Returns the 3x3 affine2d matrix to perform a rotation of a 2D vector around the Z axis. // Arguments: @@ -93,7 +103,7 @@ function affine2d_mirror(v) = // Function: affine2d_skew() // Usage: -// affine2d_skew(xa, ya) +// mat = affine2d_skew(xa, ya); // Description: // Returns the 3x3 affine2d matrix to skew a 2D vector along the XY plane. // Arguments: @@ -108,7 +118,7 @@ function affine2d_skew(xa, ya) = [ // Function: affine2d_chain() // Usage: -// affine2d_chain(affines) +// mat = affine2d_chain(affines); // Description: // Returns a 3x3 affine2d transformation matrix which results from applying each matrix in `affines` in order. // Arguments: @@ -123,11 +133,15 @@ function affine2d_chain(affines, _m=undef, _i=0) = // Function: affine3d_identity() +// Usage: +// mat = affine3d_identity(); // Description: Create a 4x4 affine3d identity matrix. function affine3d_identity() = ident(4); // Function: affine3d_translate() +// Usage: +// mat = affine3d_translate(v); // Description: // Returns the 4x4 affine3d matrix to perform a 3D translation. // Arguments: @@ -141,6 +155,8 @@ function affine3d_translate(v) = [ // Function: affine3d_scale() +// Usage: +// mat = affine3d_scale(v); // Description: // Returns the 4x4 affine3d matrix to perform a 3D scaling transformation. // Arguments: @@ -154,6 +170,8 @@ function affine3d_scale(v) = [ // Function: affine3d_xrot() +// Usage: +// mat = affine3d_xrot(ang); // Description: // Returns the 4x4 affine3d matrix to perform a rotation of a 3D vector around the X axis. // Arguments: @@ -167,6 +185,8 @@ function affine3d_xrot(ang) = [ // Function: affine3d_yrot() +// Usage: +// mat = affine3d_yrot(ang); // Description: // Returns the 4x4 affine3d matrix to perform a rotation of a 3D vector around the Y axis. // Arguments: @@ -181,7 +201,7 @@ function affine3d_yrot(ang) = [ // Function: affine3d_zrot() // Usage: -// affine3d_zrot(ang) +// mat = affine3d_zrot(ang); // Description: // Returns the 4x4 affine3d matrix to perform a rotation of a 3D vector around the Z axis. // Arguments: @@ -196,7 +216,7 @@ function affine3d_zrot(ang) = [ // Function: affine3d_rot_by_axis() // Usage: -// affine3d_rot_by_axis(u, ang); +// mat = affine3d_rot_by_axis(u, ang); // Description: // Returns the 4x4 affine3d matrix to perform a rotation of a 3D vector around an axis. // Arguments: @@ -219,7 +239,7 @@ function affine3d_rot_by_axis(u, ang) = // Function: affine3d_rot_from_to() // Usage: -// affine3d_rot_from_to(from, to); +// mat = affine3d_rot_from_to(from, to); // Description: // Returns the 4x4 affine3d matrix to perform a rotation of a 3D vector from one vector direction to another. // Arguments: @@ -246,16 +266,16 @@ function affine3d_rot_from_to(from, to) = // Function: affine_frame_map() // Usage: -// map = affine_frame_map(x=v1,y=v2); -// map = affine_frame_map(x=v1,z=v2); -// map = affine_frame_map(y=v1,y=v2); -// map = affine_frame_map(v1,v2,v3); +// map = affine_frame_map(v1, v2, v3); +// map = affine_frame_map(x=VECTOR1, y=VECTOR2, ); +// map = affine_frame_map(x=VECTOR1, z=VECTOR2, ); +// map = affine_frame_map(y=VECTOR1, y=VECTOR2, ); // Description: // Returns a transformation that maps one coordinate frame to another. You must specify two or three of `x`, `y`, and `z`. The specified // axes are mapped to the vectors you supplied. If you give two inputs, the third vector is mapped to the appropriate normal to maintain a right hand coordinate system. // If the vectors you give are orthogonal the result will be a rotation and the `reverse` parameter will supply the inverse map, which enables you // to map two arbitrary coordinate systems to each other by using the canonical coordinate system as an intermediary. You cannot use the `reverse` option -// with non-orthogonal inputs. +// with non-orthogonal inputs. // Arguments: // x = Destination vector for x axis // y = Destination vector for y axis @@ -320,7 +340,7 @@ function affine3d_mirror(v) = // Function: affine3d_skew() // Usage: -// mat = affine3d_skew([sxy], [sxz], [syx], [syz], [szx], [szy]); +// mat = affine3d_skew(, , , , , ); // Description: // Returns the 4x4 affine3d matrix to perform a skew transformation. // Arguments: @@ -340,7 +360,7 @@ function affine3d_skew(sxy=0, sxz=0, syx=0, syz=0, szx=0, szy=0) = [ // Function: affine3d_skew_xy() // Usage: -// affine3d_skew_xy(xa, ya) +// mat = affine3d_skew_xy(xa, ya); // Description: // Returns the 4x4 affine3d matrix to perform a skew transformation along the XY plane. // Arguments: @@ -356,7 +376,7 @@ function affine3d_skew_xy(xa, ya) = [ // Function: affine3d_skew_xz() // Usage: -// affine3d_skew_xz(xa, za) +// mat = affine3d_skew_xz(xa, za); // Description: // Returns the 4x4 affine3d matrix to perform a skew transformation along the XZ plane. // Arguments: @@ -372,7 +392,7 @@ function affine3d_skew_xz(xa, za) = [ // Function: affine3d_skew_yz() // Usage: -// affine3d_skew_yz(ya, za) +// mat = affine3d_skew_yz(ya, za); // Description: // Returns the 4x4 affine3d matrix to perform a skew transformation along the YZ plane. // Arguments: @@ -388,7 +408,7 @@ function affine3d_skew_yz(ya, za) = [ // Function: affine3d_chain() // Usage: -// affine3d_chain(affines) +// mat = affine3d_chain(affines); // Description: // Returns a 4x4 affine3d transformation matrix which results from applying each matrix in `affines` in order. // Arguments: @@ -400,7 +420,7 @@ function affine3d_chain(affines, _m=undef, _i=0) = // Function: apply() // Usage: -// pts = apply(transform, points) +// pts = apply(transform, points); // Description: // Applies the specified transformation matrix to a point list (or single point). Both inputs can be 2d or 3d, and it is also allowed // to supply 3d transformations with 2d data as long as the the only action on the z coordinate is a simple scaling. @@ -425,7 +445,7 @@ function apply(transform,points) = // Function: apply_list() // Usage: -// pts = apply_list(points, transform_list) +// pts = apply_list(points, transform_list); // Description: // Transforms the specified point list (or single point) using a list of transformation matrices. Transformations on // the list are applied in the order they appear in the list (as in right multiplication of matrices). Both inputs can be @@ -457,7 +477,7 @@ function apply_list(points,transform_list) = // Function: is_2d_transform() // Usage: -// is_2d_transform(t) +// x = is_2d_transform(t); // Description: // Checks if the input is a 3d transform that does not act on the z coordinate, except // possibly for a simple scaling of z. Note that an input which is only a zscale returns false. @@ -469,7 +489,7 @@ function is_2d_transform(t) = // z-parameters are zero, except we allow t[2][ // Function: rot_decode() // Usage: -// [angle,axis,cp,translation] = rot_decode(rotation) +// info = rot_decode(rotation); // Returns: [angle,axis,cp,translation] // Description: // Given an input 3d rigid transformation operator (one composed of just rotations and translations) // represented as a 4x4 matrix, compute the rotation and translation parameters of the operator. diff --git a/arrays.scad b/arrays.scad index ab134c4d..cbc7e05d 100644 --- a/arrays.scad +++ b/arrays.scad @@ -1,10 +1,8 @@ ////////////////////////////////////////////////////////////////////// // LibFile: arrays.scad // List and Array manipulation functions. -// To use, add the following lines to the beginning of your file: -// ``` -// use -// ``` +// Includes: +// include ////////////////////////////////////////////////////////////////////// diff --git a/attachments.scad b/attachments.scad index 2c174106..7b893dee 100644 --- a/attachments.scad +++ b/attachments.scad @@ -1,10 +1,8 @@ ////////////////////////////////////////////////////////////////////// // LibFile: attachments.scad // This is the file that handles attachments and orientation of children. -// To use, add the following lines to the beginning of your file: -// ``` +// Includes: // include -// ``` ////////////////////////////////////////////////////////////////////// diff --git a/beziers.scad b/beziers.scad index 23735c9b..0549a2df 100644 --- a/beziers.scad +++ b/beziers.scad @@ -1,11 +1,9 @@ ////////////////////////////////////////////////////////////////////// // LibFile: beziers.scad // Bezier functions and modules. -// To use, add the following lines to the beginning of your file: -// ``` +// Includes: // include // include -// ``` ////////////////////////////////////////////////////////////////////// diff --git a/bottlecaps.scad b/bottlecaps.scad index 01cc0983..4dbd4cd4 100644 --- a/bottlecaps.scad +++ b/bottlecaps.scad @@ -1,11 +1,9 @@ ////////////////////////////////////////////////////////////////////// // LibFile: bottlecaps.scad // Bottle caps and necks for PCO18XX standard plastic beverage bottles. -// To use, add the following lines to the beginning of your file: -// ``` +// Includes: // include // include -// ``` ////////////////////////////////////////////////////////////////////// diff --git a/common.scad b/common.scad index d1d4021e..2354ebe8 100644 --- a/common.scad +++ b/common.scad @@ -1,10 +1,8 @@ ////////////////////////////////////////////////////////////////////// // LibFile: common.scad // Common functions used in argument processing. -// To use, include this line at the top of your file: -// ``` -// use -// ``` +// Includes: +// include ////////////////////////////////////////////////////////////////////// diff --git a/constants.scad b/constants.scad index ed5bd806..3444981d 100644 --- a/constants.scad +++ b/constants.scad @@ -1,10 +1,8 @@ ////////////////////////////////////////////////////////////////////// // LibFile: constants.scad // Useful Constants. -// To use this, add the following line to the top of your file. -// ``` +// Includes: // include -// ``` ////////////////////////////////////////////////////////////////////// diff --git a/coords.scad b/coords.scad index 3d8be118..8ab429b7 100644 --- a/coords.scad +++ b/coords.scad @@ -1,10 +1,8 @@ ////////////////////////////////////////////////////////////////////// // LibFile: coords.scad // Coordinate transformations and coordinate system conversions. -// To use, add the following lines to the beginning of your file: -// ``` -// use -// ``` +// Includes: +// include ////////////////////////////////////////////////////////////////////// diff --git a/cubetruss.scad b/cubetruss.scad index b372b751..f4c9a0ab 100644 --- a/cubetruss.scad +++ b/cubetruss.scad @@ -1,11 +1,9 @@ ////////////////////////////////////////////////////////////////////////// -// Libfile: cubetruss.scad +// LibFile: cubetruss.scad // Parts for making modular open-frame cross-braced trusses and connectors. -// To use, add the following lines to the beginning of your file: -// ``` +// Includes: // include // include -// ``` ////////////////////////////////////////////////////////////////////////// $cubetruss_size = 30; @@ -16,7 +14,7 @@ $cubetruss_clip_thickness = 1.6; // Function: cubetruss_dist() // Usage: -// cubetruss_dist(cubes, gaps, [size], [strut]); +// cubetruss_dist(cubes, gaps, , ); // Description: // Function to calculate the length of a cubetruss truss. // Arguments: @@ -24,7 +22,8 @@ $cubetruss_clip_thickness = 1.6; // gaps = The number of extra strut widths to add in, corresponding to each time a truss butts up against another. // size = The length of each side of the cubetruss cubes. Default: `$cubetruss_size` (usually 30) // strut = The width of the struts on the cubetruss cubes. Default: `$cubetruss_strut_size` (usually 3) -function cubetruss_dist(cubes=0, gaps=0, size=undef, strut=undef) = +// Topics: Trusses +function cubetruss_dist(cubes=0, gaps=0, size, strut) = let( size = is_undef(size)? $cubetruss_size : size, strut = is_undef(strut)? $cubetruss_strut_size : strut @@ -33,22 +32,24 @@ function cubetruss_dist(cubes=0, gaps=0, size=undef, strut=undef) = // Module: cubetruss_segment() // Usage: -// cubetruss_segment([size], [strut], [bracing]); +// cubetruss_segment(, , ); // Description: // Creates a single cubetruss cube segment. // Arguments: // size = The length of each side of the cubetruss cubes. Default: `$cubetruss_size` (usually 30) // strut = The width of the struts on the cubetruss cubes. Default: `$cubetruss_strut_size` (usually 3) // bracing = If true, adds internal cross-braces. Default: `$cubetruss_bracing` (usually true) +// --- // anchor = Translate so anchor point is at origin (0,0,0). See [anchor](attachments.scad#anchor). Default: `CENTER` // spin = Rotate this many degrees around the Z axis. See [spin](attachments.scad#spin). Default: `0` // orient = Vector to rotate top towards. See [orient](attachments.scad#orient). Default: `UP` +// Topics: Attachable, Trusses // Examples: // cubetruss_segment(bracing=false); // cubetruss_segment(bracing=true); // cubetruss_segment(strut=4); // cubetruss_segment(size=40); -module cubetruss_segment(size=undef, strut=undef, bracing=undef, anchor=CENTER, spin=0, orient=UP) { +module cubetruss_segment(size, strut, bracing, anchor=CENTER, spin=0, orient=UP) { size = is_undef(size)? $cubetruss_size : size; strut = is_undef(strut)? $cubetruss_strut_size : strut; bracing = is_undef(bracing)? $cubetruss_bracing : bracing; @@ -100,7 +101,7 @@ module cubetruss_segment(size=undef, strut=undef, bracing=undef, anchor=CENTER, // Module: cubetruss_clip() // Usage: -// cubetruss_clip(extents, [size], [strut], [clipthick]); +// cubetruss_clip(extents, , , ); // Description: // Creates a pair of clips to add onto the end of a truss. // Arguments: @@ -108,14 +109,16 @@ module cubetruss_segment(size=undef, strut=undef, bracing=undef, anchor=CENTER, // size = The length of each side of the cubetruss cubes. Default: `$cubetruss_size` (usually 30) // strut = The width of the struts on the cubetruss cubes. Default: `$cubetruss_strut_size` (usually 3) // clipthick = The thickness of the clip. Default: `$cubetruss_clip_thickness` (usually 1.6) +// --- // anchor = Translate so anchor point is at origin (0,0,0). See [anchor](attachments.scad#anchor). Default: `CENTER` // spin = Rotate this many degrees around the Z axis. See [spin](attachments.scad#spin). Default: `0` // orient = Vector to rotate top towards. See [orient](attachments.scad#orient). Default: `UP` +// Topics: Attachable, Trusses // Examples: // cubetruss_clip(extents=2); // cubetruss_clip(extents=1); // cubetruss_clip(clipthick=2.5); -module cubetruss_clip(extents=1, size=undef, strut=undef, clipthick=undef, anchor=CENTER, spin=0, orient=UP) { +module cubetruss_clip(extents=1, size, strut, clipthick, anchor=CENTER, spin=0, orient=UP) { size = is_undef(size)? $cubetruss_size : size; strut = is_undef(strut)? $cubetruss_strut_size : strut; clipthick = is_undef(clipthick)? $cubetruss_clip_thickness : clipthick; @@ -162,7 +165,7 @@ module cubetruss_clip(extents=1, size=undef, strut=undef, clipthick=undef, ancho // Module: cubetruss_foot() // Usage: -// cubetruss_foot(w, [size], [strut], [clipthick]); +// cubetruss_foot(w, , , ); // Description: // Creates a foot that can be clipped onto the bottom of a truss for support. // Arguments: @@ -170,13 +173,15 @@ module cubetruss_clip(extents=1, size=undef, strut=undef, clipthick=undef, ancho // size = The length of each side of the cubetruss cubes. Default: `$cubetruss_size` (usually 30) // strut = The width of the struts on the cubetruss cubes. Default: `$cubetruss_strut_size` (usually 3) // clipthick = The thickness of the clips. Default: `$cubetruss_clip_thickness` (usually 1.6) +// --- // anchor = Translate so anchor point is at origin (0,0,0). See [anchor](attachments.scad#anchor). Default: `CENTER` // spin = Rotate this many degrees around the Z axis. See [spin](attachments.scad#spin). Default: `0` // orient = Vector to rotate top towards. See [orient](attachments.scad#orient). Default: `UP` +// Topics: Attachable, Trusses // Examples: // cubetruss_foot(w=1); // cubetruss_foot(w=3); -module cubetruss_foot(w=1, size=undef, strut=undef, clipthick=undef, anchor=CENTER, spin=0, orient=UP) { +module cubetruss_foot(w=1, size, strut, clipthick, anchor=CENTER, spin=0, orient=UP) { size = is_undef(size)? $cubetruss_size : size; strut = is_undef(strut)? $cubetruss_strut_size : strut; clipthick = is_undef(clipthick)? $cubetruss_clip_thickness : clipthick; @@ -236,7 +241,7 @@ module cubetruss_foot(w=1, size=undef, strut=undef, clipthick=undef, anchor=CENT // Module: cubetruss_joiner() // Usage: -// cubetruss_joiner([w], [vert], [size], [strut], [clipthick]); +// cubetruss_joiner(, , , , ); // Description: // Creates a part to join two cubetruss trusses end-to-end. // Arguments: @@ -245,14 +250,16 @@ module cubetruss_foot(w=1, size=undef, strut=undef, clipthick=undef, anchor=CENT // size = The length of each side of the cubetruss cubes. Default: `$cubetruss_size` (usually 30) // strut = The width of the struts on the cubetruss cubes. Default: `$cubetruss_strut_size` (usually 3) // clipthick = The thickness of the clips. Default: `$cubetruss_clip_thickness` (usually 1.6) +// --- // anchor = Translate so anchor point is at origin (0,0,0). See [anchor](attachments.scad#anchor). Default: `CENTER` // spin = Rotate this many degrees around the Z axis. See [spin](attachments.scad#spin). Default: `0` // orient = Vector to rotate top towards. See [orient](attachments.scad#orient). Default: `UP` +// Topics: Attachable, Trusses // Examples: // cubetruss_joiner(w=1, vert=false); // cubetruss_joiner(w=1, vert=true); // cubetruss_joiner(w=2, vert=true, anchor=BOT); -module cubetruss_joiner(w=1, vert=true, size=undef, strut=undef, clipthick=undef, anchor=CENTER, spin=0, orient=UP) { +module cubetruss_joiner(w=1, vert=true, size, strut, clipthick, anchor=CENTER, spin=0, orient=UP) { size = is_undef(size)? $cubetruss_size : size; strut = is_undef(strut)? $cubetruss_strut_size : strut; clipthick = is_undef(clipthick)? $cubetruss_clip_thickness : clipthick; @@ -301,19 +308,23 @@ module cubetruss_joiner(w=1, vert=true, size=undef, strut=undef, clipthick=undef // Module: cubetruss_uclip() // Usage: -// cubetruss_uclip(dual, [size], [strut], [clipthick]); +// cubetruss_uclip(dual, , , ); // Description: +// Creates a small clip that can snap around one or two adjacent struts. // Arguments: +// dual = If true, create a clip to clip around two adjacent struts. If false, just fit around one strut. Default: true // size = The length of each side of the cubetruss cubes. Default: `$cubetruss_size` (usually 30) // strut = The width of the struts on the cubetruss cubes. Default: `$cubetruss_strut_size` (usually 3) // clipthick = The thickness of the clips. Default: `$cubetruss_clip_thickness` (usually 1.6) +// --- // anchor = Translate so anchor point is at origin (0,0,0). See [anchor](attachments.scad#anchor). Default: `CENTER` // spin = Rotate this many degrees around the Z axis. See [spin](attachments.scad#spin). Default: `0` // orient = Vector to rotate top towards. See [orient](attachments.scad#orient). Default: `UP` +// Topics: Attachable, Trusses // Examples: // cubetruss_uclip(dual=false); // cubetruss_uclip(dual=true); -module cubetruss_uclip(dual=true, size=undef, strut=undef, clipthick=undef, anchor=CENTER, spin=0, orient=UP) { +module cubetruss_uclip(dual=true, size, strut, clipthick, anchor=CENTER, spin=0, orient=UP) { size = is_undef(size)? $cubetruss_size : size; strut = is_undef(strut)? $cubetruss_strut_size : strut; clipthick = is_undef(clipthick)? $cubetruss_clip_thickness : clipthick; @@ -342,7 +353,7 @@ module cubetruss_uclip(dual=true, size=undef, strut=undef, clipthick=undef, anch // Module: cubetruss() // Usage: -// cubetruss(extents, clips, bracing, size, strut, clipthick); +// cubetruss(extents, , , , , ); // Description: // Creates a cubetruss truss, assembled out of one or more cubical segments. // Arguments: @@ -352,9 +363,11 @@ module cubetruss_uclip(dual=true, size=undef, strut=undef, clipthick=undef, anch // strut = The width of the struts on the cubetruss cubes. Default: `$cubetruss_strut_size` (usually 3) // bracing = If true, adds internal cross-braces. Default: `$cubetruss_bracing` (usually true) // clipthick = The thickness of the clips. Default: `$cubetruss_clip_thickness` (usually 1.6) +// --- // anchor = Translate so anchor point is at origin (0,0,0). See [anchor](attachments.scad#anchor). Default: `CENTER` // spin = Rotate this many degrees around the Z axis. See [spin](attachments.scad#spin). Default: `0` // orient = Vector to rotate top towards. See [orient](attachments.scad#orient). Default: `UP` +// Topics: Attachable, Trusses // Examples(FlatSpin): // cubetruss(extents=3); // cubetruss(extents=3, clips=FRONT); @@ -362,7 +375,7 @@ module cubetruss_uclip(dual=true, size=undef, strut=undef, clipthick=undef, anch // cubetruss(extents=[2,3]); // cubetruss(extents=[1,4,2]); // cubetruss(extents=[1,4,2], bracing=false); -module cubetruss(extents=6, clips=[], bracing=undef, size=undef, strut=undef, clipthick=undef, anchor=CENTER, spin=0, orient=UP) { +module cubetruss(extents=6, clips=[], bracing, size, strut, clipthick, anchor=CENTER, spin=0, orient=UP) { clips = is_vector(clips)? [clips] : clips; size = is_undef(size)? $cubetruss_size : size; strut = is_undef(strut)? $cubetruss_strut_size : strut; @@ -410,7 +423,7 @@ module cubetruss(extents=6, clips=[], bracing=undef, size=undef, strut=undef, cl // Module: cubetruss_corner() // Usage: -// cubetruss_corner(h, extents, [bracing], [size], [strut], [clipthick); +// cubetruss_corner(h, extents, , , , ); // Description: // Creates a corner cubetruss with extents jutting out in one or more directions. // Arguments: @@ -420,16 +433,18 @@ module cubetruss(extents=6, clips=[], bracing=undef, size=undef, strut=undef, cl // strut = The width of the struts on the cubetruss cubes. Default: `$cubetruss_strut_size` (usually 3) // bracing = If true, adds internal cross-braces. Default: `$cubetruss_bracing` (usually true) // clipthick = The thickness of the clips. Default: `$cubetruss_clip_thickness` (usually 1.6) +// --- // anchor = Translate so anchor point is at origin (0,0,0). See [anchor](attachments.scad#anchor). Default: `CENTER` // spin = Rotate this many degrees around the Z axis. See [spin](attachments.scad#spin). Default: `0` // orient = Vector to rotate top towards. See [orient](attachments.scad#orient). Default: `UP` +// Topics: Attachable, Trusses // Examples(FlatSpin): // cubetruss_corner(extents=2); // cubetruss_corner(extents=2, h=2); // cubetruss_corner(extents=[3,3,0,0,2]); // cubetruss_corner(extents=[3,0,3,0,2]); // cubetruss_corner(extents=[3,3,3,3,2]); -module cubetruss_corner(h=1, extents=[1,1,0,0,1], bracing=undef, size=undef, strut=undef, clipthick=undef, anchor=CENTER, spin=0, orient=UP) { +module cubetruss_corner(h=1, extents=[1,1,0,0,1], bracing, size, strut, clipthick, anchor=CENTER, spin=0, orient=UP) { size = is_undef(size)? $cubetruss_size : size; strut = is_undef(strut)? $cubetruss_strut_size : strut; bracing = is_undef(bracing)? $cubetruss_bracing : bracing; diff --git a/debug.scad b/debug.scad index 68b4f321..0fc5561a 100644 --- a/debug.scad +++ b/debug.scad @@ -1,11 +1,9 @@ ////////////////////////////////////////////////////////////////////// // LibFile: debug.scad // Helpers to make debugging OpenScad code easier. -// To use, add the following lines to the beginning of your file: -// ``` +// Includes: // include // include -// ``` ////////////////////////////////////////////////////////////////////// diff --git a/distributors.scad b/distributors.scad index 026dc721..483aa00c 100644 --- a/distributors.scad +++ b/distributors.scad @@ -1,10 +1,8 @@ ////////////////////////////////////////////////////////////////////// // LibFile: distributors.scad // Functions and modules to distribute children or copies of children. -// To use, add the following lines to the beginning of your file: -// ``` +// Includes: // include -// ``` ////////////////////////////////////////////////////////////////////// diff --git a/edges.scad b/edges.scad index a81c591c..72a838ca 100644 --- a/edges.scad +++ b/edges.scad @@ -1,10 +1,8 @@ ////////////////////////////////////////////////////////////////////// // LibFile: edges.scad // Routines to work with edge sets and edge set descriptors. -// To use this, add the following line to the top of your file. -// ``` +// Includes: // include -// ``` ////////////////////////////////////////////////////////////////////// diff --git a/geometry.scad b/geometry.scad index 3e3525d3..7fa07cc6 100644 --- a/geometry.scad +++ b/geometry.scad @@ -1,10 +1,8 @@ ////////////////////////////////////////////////////////////////////// // LibFile: geometry.scad // Geometry helpers. -// To use, add the following lines to the beginning of your file: -// ``` -// use -// ``` +// Includes: +// include ////////////////////////////////////////////////////////////////////// diff --git a/hingesnaps.scad b/hingesnaps.scad index de6f3c6b..3211c882 100644 --- a/hingesnaps.scad +++ b/hingesnaps.scad @@ -1,11 +1,9 @@ ////////////////////////////////////////////////////////////////////// // LibFile: hingesnaps.scad // Useful hinge mask and snaps shapes. -// To use, add the following lines to the beginning of your file: -// ``` +// Includes: // include // include -// ``` ////////////////////////////////////////////////////////////////////// diff --git a/hull.scad b/hull.scad index 5ca23e17..04737159 100644 --- a/hull.scad +++ b/hull.scad @@ -1,13 +1,11 @@ ////////////////////////////////////////////////////////////////////// // LibFile: hull.scad // Functions to create 2D and 3D convex hulls. -// To use, add the following line to the beginning of your file: -// ``` -// include -// include -// ``` // Derived from Oskar Linde's Hull: // - https://github.com/openscad/scad-utils +// Includes: +// include +// include ////////////////////////////////////////////////////////////////////// diff --git a/involute_gears.scad b/involute_gears.scad index 86528b19..b9400273 100644 --- a/involute_gears.scad +++ b/involute_gears.scad @@ -16,12 +16,9 @@ // implemented it from scratch from the descriptions and equations on Wikipedia // and the web, using Mathematica for calculations and testing, and I now // release it into the public domain. -// . -// To use, add the following line to the beginning of your file: -// ``` +// Includes: // include // include -// ``` ////////////////////////////////////////////////////////////////////////////////////////////// diff --git a/joiners.scad b/joiners.scad index 38594a84..11815074 100644 --- a/joiners.scad +++ b/joiners.scad @@ -1,11 +1,9 @@ ////////////////////////////////////////////////////////////////////// // LibFile: joiners.scad // Snap-together joiners. -// To use, add the following lines to the beginning of your file: -// ``` +// Includes: // include // include -// ``` ////////////////////////////////////////////////////////////////////// diff --git a/knurling.scad b/knurling.scad index c2c6f522..7d3fb72a 100644 --- a/knurling.scad +++ b/knurling.scad @@ -1,10 +1,8 @@ ////////////////////////////////////////////////////////////////////// // LibFile: knurling.scad // Shapes and masks for knurling cylinders. -// To use, add the following lines to the beginning of your file: -// ``` +// Includes: // include -// ``` ////////////////////////////////////////////////////////////////////// diff --git a/linear_bearings.scad b/linear_bearings.scad index fe039f26..1fc50472 100644 --- a/linear_bearings.scad +++ b/linear_bearings.scad @@ -1,11 +1,9 @@ ////////////////////////////////////////////////////////////////////// // LibFile: linear_bearings.scad // Linear Bearing clips/holders. -// To use, add these lines to the top of your file: -// ``` +// Includes: // include // include -// ``` ////////////////////////////////////////////////////////////////////// diff --git a/masks.scad b/masks.scad index b421e7db..ce176aa8 100644 --- a/masks.scad +++ b/masks.scad @@ -1,10 +1,8 @@ ////////////////////////////////////////////////////////////////////// // LibFile: masks.scad // Masking shapes. -// To use, add the following lines to the beginning of your file: -// ``` +// Includes: // include -// ``` ////////////////////////////////////////////////////////////////////// diff --git a/math.scad b/math.scad index a2b811d4..76fe0e92 100644 --- a/math.scad +++ b/math.scad @@ -1,10 +1,8 @@ ////////////////////////////////////////////////////////////////////// // LibFile: math.scad // Math helper functions. -// To use, add the following lines to the beginning of your file: -// ``` -// use -// ``` +// Includes: +// include ////////////////////////////////////////////////////////////////////// diff --git a/metric_screws.scad b/metric_screws.scad index 01ae5aa4..197ee399 100644 --- a/metric_screws.scad +++ b/metric_screws.scad @@ -1,11 +1,9 @@ ////////////////////////////////////////////////////////////////////// // LibFile: metric_screws.scad // Screws, Bolts, and Nuts. -// To use, include the following lines at the top of your file: -// ``` +// Includes: // include // include -// ``` ////////////////////////////////////////////////////////////////////// diff --git a/mutators.scad b/mutators.scad index 2a2556f8..1ad60200 100644 --- a/mutators.scad +++ b/mutators.scad @@ -1,10 +1,8 @@ ////////////////////////////////////////////////////////////////////// // LibFile: transforms.scad // Functions and modules to mutate children in various ways. -// To use, add the following lines to the beginning of your file: -// ``` +// Includes: // include -// ``` ////////////////////////////////////////////////////////////////////// diff --git a/nema_steppers.scad b/nema_steppers.scad index 2244806a..d3851924 100644 --- a/nema_steppers.scad +++ b/nema_steppers.scad @@ -1,11 +1,9 @@ ////////////////////////////////////////////////////////////////////// // LibFile: nema_steppers.scad // Masks and models for NEMA stepper motors. -// To use, add these lines to the top of your file: -// ``` +// Includes: // include // include -// ``` ////////////////////////////////////////////////////////////////////// diff --git a/partitions.scad b/partitions.scad index c46134c8..7ef55e7e 100644 --- a/partitions.scad +++ b/partitions.scad @@ -1,11 +1,9 @@ ////////////////////////////////////////////////////////////////////// // LibFile: partitions.scad // Modules to help partition large objects into smaller parts that can be reassembled. -// To use, add the following lines to the beginning of your file: -// ``` +// Includes: // include // include -// ``` ////////////////////////////////////////////////////////////////////// diff --git a/paths.scad b/paths.scad index f7bfe290..a8cfd22c 100644 --- a/paths.scad +++ b/paths.scad @@ -1,10 +1,8 @@ ////////////////////////////////////////////////////////////////////// // LibFile: paths.scad // Support for polygons and paths. -// To use, add the following lines to the beginning of your file: -// ``` +// Includes: // include -// ``` ////////////////////////////////////////////////////////////////////// diff --git a/phillips_drive.scad b/phillips_drive.scad index 3288722f..9ab829ad 100644 --- a/phillips_drive.scad +++ b/phillips_drive.scad @@ -1,11 +1,9 @@ ////////////////////////////////////////////////////////////////////// // LibFile: phillips_drive.scad // Phillips driver bits -// To use, add these lines to the top of your file: -// ``` +// Includes: // include // include -// ``` ////////////////////////////////////////////////////////////////////// diff --git a/polyhedra.scad b/polyhedra.scad index a4cf00e5..0ea06cb2 100644 --- a/polyhedra.scad +++ b/polyhedra.scad @@ -1,11 +1,9 @@ ////////////////////////////////////////////////////////////////////// // LibFile: polyhedra.scad // Useful platonic, archimedian, and catalan polyhedra. -// To use, add the following lines to the beginning of your file: -// ``` +// Includes: // include // include -// ``` ////////////////////////////////////////////////////////////////////// diff --git a/primitives.scad b/primitives.scad index 98d63678..ad7ac4f9 100644 --- a/primitives.scad +++ b/primitives.scad @@ -2,10 +2,8 @@ // LibFile: primitives.scad // The basic built-in shapes, reworked to integrate better with // other BOSL2 library shapes and utilities. -// To use, add the following lines to the beginning of your file: -// ``` +// Includes: // include -// ``` ////////////////////////////////////////////////////////////////////// diff --git a/quaternions.scad b/quaternions.scad index e21801c1..b01314c4 100644 --- a/quaternions.scad +++ b/quaternions.scad @@ -1,10 +1,8 @@ /////////////////////////////////////////// // LibFile: quaternions.scad // Support for Quaternions. -// To use, add the following line to the beginning of your file: -// ``` +// Includes: // include -// ``` /////////////////////////////////////////// diff --git a/queues.scad b/queues.scad index f2e2d000..0a496140 100644 --- a/queues.scad +++ b/queues.scad @@ -1,11 +1,9 @@ ////////////////////////////////////////////////////////////////////// // LibFile: queues.scad // Queue data structure implementation. -// To use, add the following lines to the beginning of your file: -// ``` -// use -// use -// ``` +// Includes: +// include +// include ////////////////////////////////////////////////////////////////////// diff --git a/regions.scad b/regions.scad index acd66d98..7c4d773e 100644 --- a/regions.scad +++ b/regions.scad @@ -1,10 +1,8 @@ ////////////////////////////////////////////////////////////////////// // LibFile: regions.scad // Regions and 2D boolean geometry -// To use, add the following lines to the beginning of your file: -// ``` -// use -// ``` +// Includes: +// include ////////////////////////////////////////////////////////////////////// diff --git a/rounding.scad b/rounding.scad index c02432d0..bf95cd79 100644 --- a/rounding.scad +++ b/rounding.scad @@ -2,11 +2,9 @@ // LibFile: rounding.scad // Routines to create rounded corners, with either circular rounding, // or continuous curvature rounding with no sudden curvature transitions. -// To use, add the following lines to the beginning of your file: -// ``` +// Includes: // include // include -// ``` ////////////////////////////////////////////////////////////////////// include include diff --git a/screws.scad b/screws.scad index 03ba680f..4368068b 100644 --- a/screws.scad +++ b/screws.scad @@ -1,11 +1,9 @@ ////////////////////////////////////////////////////////////////////// // LibFile: screws.scad // Functions and modules for creating metric and UTS standard screws and nuts. -// To use, add the following lines to the beginning of your file: -// ``` +// Includes: // include // include -// ``` ////////////////////////////////////////////////////////////////////// include diff --git a/scripts/docs_gen.py b/scripts/docs_gen.py index d8849a97..9476f7ba 100755 --- a/scripts/docs_gen.py +++ b/scripts/docs_gen.py @@ -171,12 +171,7 @@ class ImageProcessing(object): print("") return - stdlibs = ["std.scad", "debug.scad"] script = "" - for lib in stdlibs: - script += "include \n" % lib - if libfile not in stdlibs: - script += "include \n" % libfile for line in self.commoncode: script += line+"\n" for line in code: @@ -334,12 +329,16 @@ class LeafNode(object): self.name = "" self.leaftype = "" self.status = "" - self.description = [] + self.topics = [] self.usages = [] + self.description = [] + self.figures = [] + self.returns = [] + self.customs = [] self.arguments = [] + self.named_arguments = [] self.anchors = [] self.side_effects = [] - self.figures = [] self.examples = [] @classmethod @@ -401,6 +400,12 @@ class LeafNode(object): dummy, status = line.split(":", 1) self.status = status.strip() continue + if line.startswith("Topics:"): + dummy, topic_line = line.split(":", 1) + topics = [] + for topic in topic_line.split(","): + self.topics.append(topic.strip()) + continue if line.startswith("Usage:"): dummy, title = line.split(":", 1) title = title.strip() @@ -419,6 +424,20 @@ class LeafNode(object): lines, block = get_comment_block(lines, prefix) self.description.extend(block) continue + if line.startswith("Returns:"): + dummy, desc = line.split(":", 1) + desc = desc.strip() + if desc: + self.returns.append(desc) + lines, block = get_comment_block(lines, prefix) + self.returns.extend(block) + continue + if line.startswith("Custom:"): + dummy, title = line.split(":", 1) + title = title.strip() + lines, block = get_comment_block(lines, prefix) + self.customs.append( (title, block) ) + continue m = figpat.match(line) if m: # Figure(TYPE): plural = m.group(1) == "Figures" @@ -435,7 +454,11 @@ class LeafNode(object): continue if line.startswith("Arguments:"): lines, block = get_comment_block(lines, prefix) + named = False for line in block: + if line.strip() == "---": + named = True + continue if "=" not in line: print("Error in {}: Could not parse line in Argument block. Missing '='.".format(self.name)) print("Line read was:") @@ -444,7 +467,10 @@ class LeafNode(object): argname, argdesc = line.split("=", 1) argname = argname.strip() argdesc = argdesc.strip() - self.arguments.append([argname, argdesc]) + if named: + self.named_arguments.append([argname, argdesc]) + else: + self.arguments.append([argname, argdesc]) continue if line.startswith("Extra Anchors:") or line.startswith("Anchors:"): lines, block = get_comment_block(lines, prefix) @@ -488,7 +514,7 @@ class LeafNode(object): return lines - def gen_md(self, fileroot, imgroot): + def gen_md(self, fileroot, imgroot, libnode, sectnode): out = [] if self.name: out.append("### " + mkdn_esc(self.name)) @@ -505,14 +531,14 @@ class LeafNode(object): out.append("- {0}".format(mkdn_esc(usage))) out.append("") if self.description: - out.append("**Description**:") + out.append("**Description:**") for line in self.description: out.append(mkdn_esc(line)) out.append("") fignum = 0 for title, excode, extype in self.figures: fignum += 1 - extitle = "**Figure {0}**:".format(fignum) + extitle = "**Figure {0}:**".format(fignum) if title: extitle += " " + mkdn_esc(title) san_name = re.sub(r"[^A-Za-z0-9_]", "", self.name) @@ -533,9 +559,21 @@ class LeafNode(object): ) ) out.append("") + if self.returns: + out.append("**Returns:**") + for line in self.returns: + out.append(mkdn_esc(line)) + out.append("") + if self.customs: + for title, block in self.customs: + out.append("**{}:**".format(title)) + for line in block: + out.append(mkdn_esc(line)) + out.append("") if self.arguments: - out.append("Argument | What it does") - out.append("--------------- | ------------------------------") + out.append("**Arguments:**") + out.append("By Position | What it does") + out.append("---------------- | ------------------------------") for argname, argdesc in self.arguments: argname = argname.replace(" / ", "` / `") out.append( @@ -545,8 +583,20 @@ class LeafNode(object): ) ) out.append("") + if self.named_arguments: + out.append("By Name | What it does") + out.append("-------------- | ------------------------------") + for argname, argdesc in self.named_arguments: + argname = argname.replace(" / ", "` / `") + out.append( + "{0:15s} | {1}".format( + "`{0}`".format(argname), + mkdn_esc(argdesc) + ) + ) + out.append("") if self.side_effects: - out.append("**Side Effects**:") + out.append("**Side Effects:**") for sfx in self.side_effects: out.append("- " + mkdn_esc(sfx)) out.append("") @@ -562,13 +612,19 @@ class LeafNode(object): ) ) out.append("") + if self.topics: + topics = [] + for topic in self.topics: + topics.append("[{0}](Topics#{0})".format(mkdn_esc(topic))) + out.append("**Related Topics:** {}".format(", ".join(topics))) + out.append("") exnum = 0 for title, excode, extype in self.examples: exnum += 1 if len(self.examples) < 2: - extitle = "**Example**:" + extitle = "**Example:**" else: - extitle = "**Example {0}**:".format(exnum) + extitle = "**Example {0}:**".format(exnum) if title: extitle += " " + mkdn_esc(title) san_name = re.sub(r"[^A-Za-z0-9_]", "", self.name) @@ -578,12 +634,25 @@ class LeafNode(object): "gif" if "Spin" in extype else "png" ) if "NORENDER" not in extype: - imgprc.add_image(fileroot+".scad", imgfile, excode, extype) + icode = [] + for line in libnode.includes: + icode.append(line) + for line in libnode.commoncode: + icode.append(line) + for line in excode: + if line.strip().startswith("--"): + icode.append(line.strip()[2:]) + else: + icode.append(line) + imgprc.add_image(fileroot+".scad", imgfile, icode, extype) if "Hide" not in extype: out.append(extitle) out.append("") - for line in excode: + for line in libnode.includes: out.append(" " + line) + for line in excode: + if not line.strip().startswith("--"): + out.append(" " + line) out.append("") if "NORENDER" not in extype: out.append( @@ -662,7 +731,7 @@ class Section(object): out.append("") return out - def gen_md(self, count, fileroot, imgroot): + def gen_md(self, count, fileroot, imgroot, libnode): out = [] if self.name: out.append("# %d. %s" % (count, mkdn_esc(self.name))) @@ -679,7 +748,7 @@ class Section(object): out.append("") for title, figcode, figtype in self.figures: Section.fignum += 1 - figtitle = "**Figure {0}**:".format(Section.fignum) + figtitle = "**Figure {0}:**".format(Section.fignum) if title: figtitle += " " + mkdn_esc(title) out.append(figtitle) @@ -702,7 +771,7 @@ class Section(object): imgprc.add_image(fileroot+".scad", imgfile, figcode, figtype) in_block = False for node in self.leaf_nodes: - out += node.gen_md(fileroot, imgroot) + out += node.gen_md(fileroot, imgroot, libnode, self) return out @@ -710,9 +779,10 @@ class LibFile(object): def __init__(self): self.name = "" self.description = [] + self.includes = [] self.commoncode = [] self.sections = [] - self.dep_sect = None + self.deprecated_section = None def parse_lines(self, lines, prefix): currsect = None @@ -739,6 +809,12 @@ class LibFile(object): lines, block = get_comment_block(lines, prefix, blanks=2) self.description.extend(block) + # Check for Includes header. + if lines and lines[0].startswith(prefix + "Includes:"): + lines.pop(0) + lines, block = get_comment_block(lines, prefix) + self.includes.extend(block) + # Check for CommonCode header. if lines and lines[0].startswith(prefix + "CommonCode:"): lines.pop(0) @@ -758,10 +834,10 @@ class LibFile(object): lines = node.parse_lines(lines, prefix) deprecated = node.status.startswith("DEPRECATED") if deprecated: - if self.dep_sect == None: - self.dep_sect = Section() - self.dep_sect.name = "Deprecations" - sect = self.dep_sect + if self.deprecated_section == None: + self.deprecated_section = Section() + self.deprecated_section.name = "Deprecations" + sect = self.deprecated_section else: if currsect == None: currsect = Section() @@ -773,7 +849,7 @@ class LibFile(object): return lines def gen_md(self, fileroot, imgroot): - imgprc.set_commoncode(self.commoncode) + imgprc.set_commoncode(self.includes + self.commoncode) out = [] if self.name: out.append("# Library File " + mkdn_esc(self.name)) @@ -789,30 +865,37 @@ class LibFile(object): out.append(mkdn_esc(line)) out.append("") in_block = False + if self.includes: + out.append("To use, add the following lines to the beginning of your file:") + out.append("```openscad") + for line in self.includes: + out.append(" " + line) + out.append("```") + out.append("") if self.name or self.description: out.append("---") out.append("") - if self.sections or self.dep_sect: + if self.sections or self.deprecated_section: out.append("# Table of Contents") out.append("") cnt = 0 for sect in self.sections: cnt += 1 out += sect.gen_md_toc(cnt) - if self.dep_sect: + if self.deprecated_section: cnt += 1 - out += self.dep_sect.gen_md_toc(cnt) + out += self.deprecated_section.gen_md_toc(cnt) out.append("---") out.append("") cnt = 0 for sect in self.sections: cnt += 1 - out += sect.gen_md(cnt, fileroot, imgroot) - if self.dep_sect: + out += sect.gen_md(cnt, fileroot, imgroot, self) + if self.deprecated_section: cnt += 1 - out += self.dep_sect.gen_md(cnt, fileroot, imgroot) + out += self.deprecated_section.gen_md(cnt, fileroot, imgroot, self) return out diff --git a/shapes.scad b/shapes.scad index a99e9f32..f453d5d5 100644 --- a/shapes.scad +++ b/shapes.scad @@ -1,10 +1,8 @@ ////////////////////////////////////////////////////////////////////// // LibFile: shapes.scad // Common useful shapes and structured objects. -// To use, add the following lines to the beginning of your file: -// ``` +// Includes: // include -// ``` ////////////////////////////////////////////////////////////////////// diff --git a/shapes2d.scad b/shapes2d.scad index 6efa3924..7a94b718 100644 --- a/shapes2d.scad +++ b/shapes2d.scad @@ -1,10 +1,8 @@ ////////////////////////////////////////////////////////////////////// // LibFile: shapes2d.scad // Common useful 2D shapes. -// To use, add the following lines to the beginning of your file: -// ``` +// Includes: // include -// ``` ////////////////////////////////////////////////////////////////////// diff --git a/skin.scad b/skin.scad index d53b09fb..2f6128c9 100644 --- a/skin.scad +++ b/skin.scad @@ -1,13 +1,11 @@ ////////////////////////////////////////////////////////////////////// // LibFile: skin.scad // Functions to skin arbitrary 2D profiles/paths in 3-space. -// To use, add the following line to the beginning of your file: -// ``` -// include -// include -// ``` // Inspired by list-comprehension-demos skin(): // - https://github.com/openscad/list-comprehension-demos/blob/master/skin.scad +// Includes: +// include +// include ////////////////////////////////////////////////////////////////////// diff --git a/sliders.scad b/sliders.scad index 466fffbe..9fed1bbc 100644 --- a/sliders.scad +++ b/sliders.scad @@ -1,11 +1,9 @@ ////////////////////////////////////////////////////////////////////// // LibFile: sliders.scad // Simple V-groove based sliders and rails. -// To use, add these lines to the beginning of your file: -// ``` +// Includes: // include // include -// ``` ////////////////////////////////////////////////////////////////////// diff --git a/stacks.scad b/stacks.scad index 4a452c0a..9e53df8a 100644 --- a/stacks.scad +++ b/stacks.scad @@ -1,11 +1,9 @@ ////////////////////////////////////////////////////////////////////// // LibFile: stacks.scad // Stack data structure implementation. -// To use, add the following lines to the beginning of your file: -// ``` -// use -// use -// ``` +// Includes: +// include +// include ////////////////////////////////////////////////////////////////////// diff --git a/std.scad b/std.scad index 94d80a06..72b5dc85 100644 --- a/std.scad +++ b/std.scad @@ -1,13 +1,11 @@ ////////////////////////////////////////////////////////////////////// // LibFile: std.scad // File that includes the standard BOSL include files. -// To use, add the following lines to the beginning of your file: -// ``` +// Includes: // include -// ``` ////////////////////////////////////////////////////////////////////// -assert(version_num()>=20190301, "BOSL2 requires OpenSCAD version 2019.03.01 or later."); +assert(version_num()>=20190500, "BOSL2 requires OpenSCAD version 2019.05 or later."); include diff --git a/strings.scad b/strings.scad index 051d450e..26be6359 100644 --- a/strings.scad +++ b/strings.scad @@ -1,10 +1,8 @@ ////////////////////////////////////////////////////////////////////// // LibFile: strings.scad // String manipulation and formatting functions. -// To use, add the following lines to the beginning of your file: -// ``` -// use -// ``` +// Includes: +// include ////////////////////////////////////////////////////////////////////// diff --git a/structs.scad b/structs.scad index c37d62aa..3352a2e5 100644 --- a/structs.scad +++ b/structs.scad @@ -1,11 +1,9 @@ ////////////////////////////////////////////////////////////////////// // LibFile: structs.scad // Struct/Dictionary manipulation functions. -// To use, add the following lines to the beginning of your file: -// ``` -// use -// use -// ``` +// Includes: +// include +// include ////////////////////////////////////////////////////////////////////// diff --git a/threading.scad b/threading.scad index 7d4ced5e..0a2e3bd9 100644 --- a/threading.scad +++ b/threading.scad @@ -1,11 +1,9 @@ ////////////////////////////////////////////////////////////////////// // LibFile: threading.scad // Triangular and Trapezoidal-Threaded Screw Rods and Nuts. -// To use, add the following lines to the beginning of your file: -// ``` +// Includes: // include // include -// ``` ////////////////////////////////////////////////////////////////////// diff --git a/torx_drive.scad b/torx_drive.scad index 1206b332..abe28c97 100644 --- a/torx_drive.scad +++ b/torx_drive.scad @@ -1,11 +1,9 @@ ////////////////////////////////////////////////////////////////////// // LibFile: torx_drive.scad // Torx driver bits -// To use, add these lines to the top of your file: -// ``` +// Includes: // include // include -// ``` ////////////////////////////////////////////////////////////////////// diff --git a/transforms.scad b/transforms.scad index 1be45143..17a03156 100644 --- a/transforms.scad +++ b/transforms.scad @@ -1,10 +1,8 @@ ////////////////////////////////////////////////////////////////////// // LibFile: transforms.scad // Functions and modules for translation, rotation, reflection and skewing. -// To use, add the following lines to the beginning of your file: -// ``` +// Includes: // include -// ``` ////////////////////////////////////////////////////////////////////// diff --git a/triangulation.scad b/triangulation.scad index 9dbd2ef8..f389b3f0 100644 --- a/triangulation.scad +++ b/triangulation.scad @@ -1,11 +1,9 @@ ////////////////////////////////////////////////////////////////////// // LibFile: triangulation.scad // Functions to triangulate polyhedron faces. -// To use, add the following lines to the beginning of your file: -// ``` +// Includes: // include // include -// ``` ////////////////////////////////////////////////////////////////////// diff --git a/turtle3d.scad b/turtle3d.scad index 901df55e..bb557d94 100644 --- a/turtle3d.scad +++ b/turtle3d.scad @@ -2,11 +2,9 @@ // LibFile: turtle3d.scad // Three dimensional turtle graphics to generate 3d paths or sequences // of 3d transformations. -// To use, add the following lines to the beginning of your file: -// ``` +// Includes: // include // include -// ``` ////////////////////////////////////////////////////////////////////// include diff --git a/vectors.scad b/vectors.scad index d9123e10..146bdbdd 100644 --- a/vectors.scad +++ b/vectors.scad @@ -1,10 +1,8 @@ ////////////////////////////////////////////////////////////////////// // LibFile: vectors.scad // Vector math functions. -// To use, add the following lines to the beginning of your file: -// ``` -// use -// ``` +// Includes: +// include ////////////////////////////////////////////////////////////////////// diff --git a/version.scad b/version.scad index 8a19e0de..c50e9ced 100644 --- a/version.scad +++ b/version.scad @@ -1,14 +1,12 @@ ////////////////////////////////////////////////////////////////////// // LibFile: version.scad // File that provides functions to manage versioning. -// To use, add the following lines to the beginning of your file: -// ``` +// Includes: // include -// ``` ////////////////////////////////////////////////////////////////////// -BOSL_VERSION = [2,0,505]; +BOSL_VERSION = [2,0,506]; // Section: BOSL Library Version Functions diff --git a/vnf.scad b/vnf.scad index ea61bd1f..9e11a74e 100644 --- a/vnf.scad +++ b/vnf.scad @@ -1,11 +1,9 @@ ////////////////////////////////////////////////////////////////////// // LibFile: vnf.scad // VNF structures, holding Vertices 'N' Faces for use with `polyhedron().` -// To use, add the following lines to the beginning of your file: -// ``` -// use -// use -// ``` +// Includes: +// include +// include ////////////////////////////////////////////////////////////////////// diff --git a/walls.scad b/walls.scad index ebd22cef..973bba88 100644 --- a/walls.scad +++ b/walls.scad @@ -1,11 +1,9 @@ ////////////////////////////////////////////////////////////////////// // LibFile: walls.scad // Various wall constructions. -// To use, add the following lines to the beginning of your file: -// ``` +// Includes: // include // include -// ``` ////////////////////////////////////////////////////////////////////// diff --git a/wiring.scad b/wiring.scad index d16120ad..59183479 100644 --- a/wiring.scad +++ b/wiring.scad @@ -1,11 +1,9 @@ ////////////////////////////////////////////////////////////////////// // LibFile: wiring.scad // Rendering for wiring bundles -// To use, include the following line at the top of your file: -// ``` +// Includes: // include // include -// ``` //////////////////////////////////////////////////////////////////////