diff --git a/core.scad b/core.scad index 57b7b1d..afe9726 100644 --- a/core.scad +++ b/core.scad @@ -18,7 +18,7 @@ // // -// Include this file to use the library +// Include this file to use the miniumum library // include // diff --git a/docs/usage.md b/docs/usage.md index 51ddac9..d4ed394 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -14,12 +14,12 @@ The following Python modules are used and can be installed with pip: ``` pip install colorama - +pip install codespell ``` ## Installation -OpenSCAD it has to be setup to find libraries by setting the ```OPENSCADPATH``` environment variable to where you want to file your libaries and NopSCADlib needs to be installed +OpenSCAD it has to be setup to find libraries by setting the ```OPENSCADPATH``` environment variable to where you want to file your libraries and NopSCADlib needs to be installed in the directory it points to. This can be done with ```git clone https://github.com/nophead/NopSCADlib.git``` while in that directory or by downloading https://github.com/nophead/NopSCADlib/archive/master.zip and unzipping it to a directory called NopSCADlib if you don't want to use GIT. @@ -31,7 +31,7 @@ Running ```tests``` from the command line will run all the tests in the ```tests ## Directory structure -| Path | Usage | +| Path | Contents | |:-----|:------| | ```NopSCADlib``` | Top level scad files, e.g. ```lib.scad``` | | ```NopSCADlib/doc``` | Documentation like this that is not automatically generated | @@ -47,16 +47,18 @@ Running ```tests``` from the command line will run all the tests in the ```tests ## Making a project -Each project has its own directory and that is used to derive the project's name. There should also be a subdirectory called ```scad`` and a main scad file which contains the main +Each project has its own directory and that is used to derive the project's name. There should also be a subdirectory called ```scad``` and a main scad file which contains the main assembly. A skeleton project looks like this: - -```OpenSCAD -//! Project desciption in Markdown format before the first include. + +``` +//! Project description in Markdown format before the first include. include ... +//! Assembly instructions in Markdown format in front of each module that makes an assembly. module main_assembly() assembly("main") { ... @@ -66,3 +68,31 @@ if($preview) main_assembly(); ``` + +Other scad files can be added in the scad directory and included or used as reqired. + +* Subassemblies can be added in the same format as ```main_assembly()```, i.e. a module called something_assembly, taking no parameters and calling assembly("something") with +the rest of its contents passed as children. Assembly instructions should be added directly before the module definition. + +* Any printed parts should be made by a module called ```something_stl()```, taking no parameters and calling stl("something") so they appear on the BOM. + +* Any routed parts should be made by a module called ```something_dxf()```, taking no paraneters and calling dxf("something") so they appear on the BOM. + +When ```make_all``` is run from the top level directory of the project it will create the following sub-directories and populate the. :- + +| Directory | Contents | +|:----------|:---------| +| assemblies | For each assembly an assembled view and an exploded assembly view in large and small format | +| bom | A flat BOM in ```bom.txt``` for the whole project, flat BOMs in text format for each assembly and a hierarchical BOM in JSON format, ```bom.json```.| +| deps | Dependency files for each scad file in the project so subsequent builds can be incremental | +| dxfs | DXF files for all the routed parts in the project and small PNG images of them | +| stls | STL files for all the printed parts in the project and small PNG images of them | + +It will also make a Markdown assembly manual called ```readme.md``` suitable for github, a version rendered to HTML for viewing locally called ```readme.html``` and a second +HTML version called ```printme.html```. This has page breaks instead of horizontal rules and can be converted to PDF uisng Chrome. + +Each time OpenSCAD is run to produce STL, DXF or assembly views the time it takes is recorded and comared with the previous time. At the end the times are printed with the delta + from the last run and coloured red or green if they have got significantly faster or slower. This is useful for optimising the scad code for speed. + +When PNG files are made they are compared with the previous version and only updated if they have changed. When that happens a PNG difference file is created so you can +review the changes graphically. They will be deleted on the next run. diff --git a/scripts/blurb.py b/scripts/blurb.py index 73c8787..99ed66d 100644 --- a/scripts/blurb.py +++ b/scripts/blurb.py @@ -29,7 +29,7 @@ def parse_line(line): return False, line[start :] else: words = line.split() - return len(words) and (words[0] == "module" or words[0] == "function"), "" + return len(words) and (words[0] == "module" or words[0] == "function" or words[0] == 'include'), "" def _scrape_blurb(lines): """ Find Markup lines before the first function or module given a list of lines.""" diff --git a/scripts/doc_scripts.py b/scripts/doc_scripts.py index 8a8aabc..1b5d293 100644 --- a/scripts/doc_scripts.py +++ b/scripts/doc_scripts.py @@ -20,7 +20,7 @@ # # -#! Makes this document. +#! Makes this document and doc/usage.md. # from __future__ import print_function @@ -63,10 +63,15 @@ They should work with both Python 2 and Python 3. with open(dir + "/readme.html", "wt") as html_file: do_cmd(("python -m markdown -x tables " + doc_name).split(), html_file) + + with open("docs/usage.html", "wt") as html_file: + do_cmd(("python -m markdown -x tables docs/usage.md").split(), html_file) # # Spell check # do_cmd(('codespell -L od ' + doc_name).split()) + do_cmd(('codespell -L od docs/usage.md').split()) + if __name__ == '__main__': doc_scripts() diff --git a/scripts/exports.py b/scripts/exports.py index 6d405c9..953674d 100644 --- a/scripts/exports.py +++ b/scripts/exports.py @@ -83,7 +83,7 @@ def make_parts(target, part_type, parts = None): # # Find all the scad files # - lib_dir = os.environ['OPENSCADPATH'] + '/NopSCADlib' + lib_dir = os.environ['OPENSCADPATH'] + '/NopSCADlib/printed' used = [] module_suffix = '_dxf' if part_type == 'svg' else '_' + part_type for dir in [source_dir, lib_dir]: diff --git a/scripts/gallery.py b/scripts/gallery.py index 5b090b0..046f9bd 100644 --- a/scripts/gallery.py +++ b/scripts/gallery.py @@ -31,7 +31,7 @@ from shutil import copyfile from tests import update_image import sys -project_dir = '../..' +project_dirs = ['../..', 'examples'] target_dir = 'gallery' output_name = target_dir + '/readme.md' @@ -39,11 +39,12 @@ def gallery(force): if not os.path.isdir(target_dir): os.makedirs(target_dir) - projects = [i for i in os.listdir(project_dir) if os.path.isdir(project_dir + '/' + i + '/assemblies')] + + paths = sorted([pdir + '/' + i for pdir in project_dirs for i in os.listdir(pdir) if os.path.isdir(pdir + '/' + i + '/assemblies')], key = lambda s: os.path.basename(s)) with open(output_name, 'wt') as output_file: print("# A gallery of projects made with NopSCADlib", file = output_file) - for project in projects: - path = project_dir + '/' + project + for path in paths: + project = os.path.basename(path) print(project) document = path + '/readme.md' if force: diff --git a/scripts/readme.md b/scripts/readme.md index 7e1ecc5..23ff635 100644 --- a/scripts/readme.md +++ b/scripts/readme.md @@ -8,7 +8,7 @@ They should work with both Python 2 and Python 3. |:--|:--| | ```bom.py``` | Generates BOM files for the project. | | ```c14n_stl.py``` | OpenSCAD produces randomly ordered STL files. This script re-orders them consistently so that GIT can tell if they have changed or not. | -| ```doc_scripts.py``` | Makes this document. | +| ```doc_scripts.py``` | Makes this document and doc/usage.md. | | ```dxfs.py``` | Generates DXF files for all the routed parts listed on the BOM or a specified list. | | ```gallery.py``` | Finds projects and adds them to the gallery. | | ```make_all.py``` | Generates all the files for a project by running ```bom.py```, ```stls.py```, ```dxfs.py```, ```render.py``` and ```views.py```. | diff --git a/scripts/views.py b/scripts/views.py index fd76fd2..e195756 100644 --- a/scripts/views.py +++ b/scripts/views.py @@ -120,7 +120,7 @@ def views(target, do_assemblies = None): # Find all the scad files # main_blurb = None - lib_dir = os.environ['OPENSCADPATH'] + '/NopSCADlib' + lib_dir = os.environ['OPENSCADPATH'] + '/NopSCADlib/printed' for dir in [source_dir, lib_dir]: for filename in os.listdir(dir): if filename.endswith('.scad'): diff --git a/tests/strap_handle.scad b/tests/strap_handle.scad index d14aa4b..50879e9 100644 --- a/tests/strap_handle.scad +++ b/tests/strap_handle.scad @@ -17,7 +17,7 @@ // If not, see . // include <../core.scad> -use <../strap_handle.scad> +use <../printed/strap_handle.scad> length = 150; diff --git a/utils/annotation.scad b/utils/annotation.scad index 1ca4a7c..6d28e8d 100644 --- a/utils/annotation.scad +++ b/utils/annotation.scad @@ -16,9 +16,12 @@ // You should have received a copy of the GNU General Public License along with NopSCADlib. // If not, see . // -include <../core.scad> + // //! Annotation used in this documentation +// + +include <../core.scad> module label(str, scale = 0.25, valign = "baseline", halign = "left") //! Draw text that always faces the camera color("black")