From 977eb086573735255a9432102214a2b6afe712d4 Mon Sep 17 00:00:00 2001 From: Dave Cowden Date: Tue, 23 Apr 2013 20:33:39 -0400 Subject: [PATCH] now sphinxdoc works --- .gitignore | 2 +- cadquery/__init__.py | 23 +------- cadquery/cq_directive.py | 85 ++++++++++++++++++++++++++++++ cadquery/freecad_impl/exporters.py | 3 +- doc/apireference.rst | 7 +-- doc/cadquerybasics.rst | 4 +- doc/classreference.rst | 62 +++++++++++++++++++++- doc/conf.py | 7 ++- doc/examples.rst | 6 +-- doc/index.rst | 12 +---- doc/intro.rst | 12 ++--- doc/quickstart.rst | 15 +++--- doc/selectors.rst | 4 +- 13 files changed, 178 insertions(+), 64 deletions(-) create mode 100644 cadquery/cq_directive.py diff --git a/.gitignore b/.gitignore index 4381075..6c0dc9a 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,2 @@ *.pyc -sphinxdoc/_build/* +doc/_build/* diff --git a/cadquery/__init__.py b/cadquery/__init__.py index 5ac20a7..67edb26 100644 --- a/cadquery/__init__.py +++ b/cadquery/__init__.py @@ -1,21 +1,3 @@ -""" - Copyright (C) 2011-2013 Parametric Products Intellectual Holdings, LLC - - This file is part of CadQuery. - - CadQuery is free software; you can redistribute it and/or - modify it under the terms of the GNU Lesser General Public - License as published by the Free Software Foundation; either - version 2.1 of the License, or (at your option) any later version. - - CadQuery is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - Lesser General Public License for more details. - - You should have received a copy of the GNU Lesser General Public - License along with this library; If not, see -""" #these items point to the freecad implementation @@ -26,14 +8,13 @@ from .freecad_impl import exporters #these items are the common implementation #the order of these matter -from . import selectors +from .selectors import NearestToPointSelector,ParallelDirSelector,DirectionSelector,PerpendicularDirSelector,TypeSelector,DirectionMinMaxSelector,StringSyntaxSelector,Selector from .CQ import CQ,CQContext,Workplane __all__ = [ 'CQ','Workplane','plugins','selectors','Plane','BoundBox','Matrix','Vector','sortWiresByBuildOrder', - 'Shape','Vertex','Edge','Wire','Solid','Shell','Compound','exporters', - 'plugins' + 'Shape','Vertex','Edge','Wire','Solid','Shell','Compound','exporters', 'NearestToPointSelector','ParallelDirSelector','DirectionSelector','PerpendicularDirSelector','TypeSelector','DirectionMinMaxSelector','StringSyntaxSelector','Selector','plugins' ] __version__ = 0.9 \ No newline at end of file diff --git a/cadquery/cq_directive.py b/cadquery/cq_directive.py new file mode 100644 index 0000000..d898d27 --- /dev/null +++ b/cadquery/cq_directive.py @@ -0,0 +1,85 @@ +""" +A special directive for including a cq object. + +""" + +import sys, os, shutil, imp, warnings, cStringIO, re,traceback + +from cadquery import * +import StringIO +from docutils.parsers.rst import directives + + +template = """ + +.. raw:: html + +
+ %(outSVG)s +
+
+
+ +""" +template_content_indent = ' ' + + +def cq_directive(name, arguments, options, content, lineno, + content_offset, block_text, state, state_machine): + + #only consider inline snippets + plot_code = '\n'.join(content) + + # Since we don't have a filename, use a hash based on the content + #the script must define a variable called 'out', which is expected to + #be a CQ object + outSVG = "Your Script Did not assign the 'result' variable!" + + + try: + _s = StringIO.StringIO() + exec(plot_code) + + exporters.exportShape(result,"SVG",_s) + outSVG = _s.getvalue() + except: + traceback.print_exc() + outSVG = traceback.format_exc() + + #now out + # Now start generating the lines of output + lines = [] + + #get rid of new lines + outSVG = outSVG.replace('\n','') + + txtAlign = "left" + if options.has_key("align"): + txtAlign = options['align'] + + lines.extend((template % locals()).split('\n')) + + lines.extend(['::', '']) + lines.extend([' %s' % row.rstrip() + for row in plot_code.split('\n')]) + lines.append('') + + if len(lines): + state_machine.insert_input( + lines, state_machine.input_lines.source(0)) + + return [] + +def setup(app): + setup.app = app + setup.config = app.config + setup.confdir = app.confdir + + options = {'height': directives.length_or_unitless, + 'width': directives.length_or_percentage_or_unitless, + 'align': directives.unchanged + } + + app.add_directive('cq_plot', cq_directive, True, (0, 2, 0), **options) + + diff --git a/cadquery/freecad_impl/exporters.py b/cadquery/freecad_impl/exporters.py index 78c27b8..41e28b5 100644 --- a/cadquery/freecad_impl/exporters.py +++ b/cadquery/freecad_impl/exporters.py @@ -51,6 +51,7 @@ def exportShape(shape,exportType,fileLike,tolerance=0.1): The object should be already open and ready to write. The caller is responsible for closing the object """ + if isinstance(shape,cadquery.CQ): shape = shape.val() @@ -243,7 +244,7 @@ def getSVG(shape,opts=None): """ d = {'width':800,'height':240,'marginLeft':200,'marginTop':20} - + if opts: d.update(opts) diff --git a/doc/apireference.rst b/doc/apireference.rst index ba948aa..83108b6 100644 --- a/doc/apireference.rst +++ b/doc/apireference.rst @@ -4,12 +4,11 @@ CadQuery API Reference *********************** -.. automodule:: cadfile.cadutils.cadquery + .. seealso:: This page lists api methods grouped by functional area. Use :ref:`classreference` to see methods alphabetically by class. - Don't see a method you want? see :ref:`extending` Primary Objects ---------------- @@ -25,6 +24,8 @@ The sections below list methods of these objects grouped by **functional area** Initialization ---------------- +.. automodule:: cadquery + Creating new workplanes and object chains .. autosummary:: @@ -69,7 +70,6 @@ Creating 2-d constructs that can be used to create 3 d features Methods that create 3d features .. autosummary:: - Workplane.cboreHole Workplane.cskHole Workplane.hole @@ -129,6 +129,7 @@ Selectors Objects that filter and select CAD objects + .. autosummary:: NearestToPointSelector ParallelDirSelector diff --git a/doc/cadquerybasics.rst b/doc/cadquerybasics.rst index 91188c2..c101ff1 100644 --- a/doc/cadquerybasics.rst +++ b/doc/cadquerybasics.rst @@ -1,6 +1,6 @@ .. _cadquerybasics: -.. automodule:: cadfile.cadutils.cadquery +.. automodule:: cadquery ************************* Introduction to CadQuery @@ -21,7 +21,7 @@ CadQuery strives to allow scripts to read roughly as a human would describe an o For example, consider this object: -.. image:: quickstart.png +.. image:: _static/quickstart.png A human would describe this as: diff --git a/doc/classreference.rst b/doc/classreference.rst index 8fcb76a..d86fcea 100644 --- a/doc/classreference.rst +++ b/doc/classreference.rst @@ -10,7 +10,7 @@ This page documents all of the methods and functions of the CadQuery classes, or For a listing organized by functional area, see the :ref:`apireference` -.. automodule:: cadfile.cadutils.cadquery +.. automodule:: cadquery Core Classes --------------------- @@ -20,6 +20,20 @@ Core Classes Plane Workplane +Primitives +----------------- + +.. autosummary:: + + Plane + Vector + Solid + Shell + Wire + Edge + Vertex + + Selectors --------------------- @@ -33,7 +47,47 @@ Selectors DirectionMinMaxSelector StringSyntaxSelector -Classes +Geometry Classes +------------------ + +.. autoclass:: Vector + :members: + +.. autoclass:: Plane + :members: + +Shape Base Class +------------------- + +All objects inherit from Shape, which as basic manipulation methods: + +.. autoclass:: Shape + :members: + +Primitive Classes +-------------------- + +.. autoclass:: Solid + :members: + + +.. autoclass:: Shell + :members: + + +.. autoclass:: Wire + :members: + + +.. autoclass:: Edge + :members: + + +.. autoclass:: Vertex + :members: + + +Core Classes ------------------------ .. autoclass:: CQ @@ -46,6 +100,10 @@ Classes :members: :inherited-members: + +Selector Classes +------------------------ + .. autoclass:: Selector :members: diff --git a/doc/conf.py b/doc/conf.py index 0912e6b..d0ba453 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -12,9 +12,12 @@ # serve to show the default. import sys, os +import os.path +print "working path is %s" % os.getcwd() +sys.path.append("..") import cadquery -settings._target = None +#settings._target = None # If extensions (or modules to document with autodoc) are in another directory, @@ -29,7 +32,7 @@ settings._target = None # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode', 'sphinx.ext.autosummary','cadfile.cadutils.cq_directive'] +extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode', 'sphinx.ext.autosummary','cadquery.cq_directive'] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] diff --git a/doc/examples.rst b/doc/examples.rst index b4c51d2..d4461ad 100644 --- a/doc/examples.rst +++ b/doc/examples.rst @@ -4,8 +4,8 @@ CadQuery Examples ********************************* -.. automodule:: cadfile.cadutils.cadquery -.. automodule:: cadfile.cadutils.cad +.. automodule:: cadquery + The examples on this page can help you learn how to build objects with CadQuery. @@ -387,7 +387,7 @@ You can create a rotated work plane by specifying angles of rotation relative to .. cq_plot:: result = Workplane("front").box(4.0,4.0,0.25).faces(">Z").workplane() \ - .transformed(offset=cad.Vector(0,-1.5,1.0),rotate=cad.Vector(60,0,0)) \ + .transformed(offset=Vector(0,-1.5,1.0),rotate=Vector(60,0,0)) \ .rect(1.5,1.5,forConstruction=True).vertices().hole(0.25) .. topic:: Api References diff --git a/doc/index.rst b/doc/index.rst index 2454e9d..d93cf81 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -3,15 +3,10 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -Parametric Parts Documentation Home +CadQuery Documentation Home =================================== -Parametric Parts is a technology platform that offers: - * **For Users**: Customize, download, and print models easily using only a web browser. Every model is parametric. - * **For Designers**: Create models with an easy to use, fluent API called CadQuery. ( See :ref:`examples` ) - * **For Developers**: :ref:`buildservice` allows other technology platforms to build models while controlling the user - experience Contents @@ -22,17 +17,12 @@ Contents intro.rst quickstart.rst - fileformat.rst cadquerybasics.rst examples.rst apireference.rst - primitiveref.rst selectors.rst classreference.rst - restservice.rst - - roadmap.rst Indices and tables ================== diff --git a/doc/intro.rst b/doc/intro.rst index 57fdf26..024c5b4 100644 --- a/doc/intro.rst +++ b/doc/intro.rst @@ -4,15 +4,9 @@ Introduction ********************* -What is a ParametricParts Model Script? +What is CadQuery ======================================== -A Model Script is a python script that builds a 3d model in response to user inputs. - -Model Scripts are written in python. They can use two different APIs: - 1. FreeCAD Scripts, or - 2. a new, fluent-api called CadQuery. - CadQuery is an intuitive, easy-to-use language for building parametric 3D CAD models. It has several goals: * Build models with scripts that are as close as possible to how you'd describe the object to a human. @@ -28,7 +22,7 @@ CadQuery is a Python module that provides a high-level wrapper around the (`FreeCAD `_) python libraries. Where does the name CadQuery come from? -=============================== +======================================== CadQuery is inspired by ( `jQuery `_ ), a popular framework that revolutionized web development involving javascript. @@ -44,7 +38,7 @@ If you are familiar with how jQuery, you will probably recognize several jQuery Why ParametricParts instead of OpenSCAD? -================================== +============================================ CadQuery is based on FreeCAD,which is in turn based on the OpenCascade modelling kernel. CadQuery/FreeCAD scripts share many features with OpenSCAD, another open source, script based, parametric model generator. diff --git a/doc/quickstart.rst b/doc/quickstart.rst index c51d55b..ccca09f 100644 --- a/doc/quickstart.rst +++ b/doc/quickstart.rst @@ -1,10 +1,10 @@ -.. module:: cadfile.cadutils.cadquery +.. module:: cadquery .. _quickstart: *********************** -ModelScript QuickStart +CadQuery QuickStart *********************** Want a quick glimpse of Parametric Parts ModelScripts? You're at the right place! @@ -51,7 +51,7 @@ CadQuery comes with an online, interactive default model as a starting point. You should see the dynamic model creator page, which will display a sample model: - .. image:: quickstart-1.png + .. image:: _static/quickstart-1.png Take a minute to play with this model. Here are a few things to try: @@ -111,7 +111,7 @@ Now, modify the build script to use your width value to make the block by chang The value property always returns the ``user-adjusted`` value of the parameter. That's good enough for now. Click "Save Changes" and you should see your 80x60x10mm base plate, like this: - .. image:: quickstart-2.png + .. image:: _static/quickstart-2.png If you'd like to come back to this model later, the url bar links to the newly created part. @@ -135,7 +135,7 @@ This modification will do the trick: Rebuild your model by clicking "Save Model" at the bottom. Your block should look like this: - .. image:: quickstart-3.png + .. image:: _static/quickstart-3.png The code is pretty compact, and works like this: @@ -179,7 +179,7 @@ Good news!-- we can get the job done with just two lines of code. Here's the cod You should see something like this: - .. image:: quickstart-4.png + .. image:: _static/quickstart-4.png Lets Break that down a bit ^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -267,7 +267,7 @@ We can do that using the preset dictionaries in the parameter definition: Now save the model and have a look at the preset DDLB-- you'll see that you can easily switch between these configurations: - .. image:: quickstart-5.png + .. image:: _static/quickstart-5.png Done! @@ -300,6 +300,5 @@ Want to learn more? ==================== * The :ref:`examples` contains lots of examples demonstrating cadquery features - * The :ref:`cadquery_reference` describes the file format in detail * The :ref:`apireference` is a good overview of language features grouped by function * The :ref:`classreference` is the hard-core listing of all functions available. \ No newline at end of file diff --git a/doc/selectors.rst b/doc/selectors.rst index 178d12e..7febf84 100644 --- a/doc/selectors.rst +++ b/doc/selectors.rst @@ -4,7 +4,7 @@ CadQuery String Selectors ************************* -.. automodule:: cadfile.cadutils.cadquery +.. automodule:: cadquery CadQuery selector strings allow filtering various types of object lists. Most commonly, Edges, Faces, and Vertices are used, but all objects types can be filtered. @@ -69,6 +69,8 @@ Some filter types are not supported for edges. The selector usually refers to t The axis used in the listing below are for illustration: any axis would work similarly in each case. + + ========= ==================================== ===================================== ========================== Selector Selector Class Selects # objects returned ========= ==================================== ===================================== ==========================