documentation

Author: lfagundes

docs/conf.py

@@ -14,7 +14,7 @@
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
-extensions = []
+extensions = ['sphinx.ext.autodoc']
 
 templates_path = ['_templates']
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']

docs/index.rst

@@ -8,5 +8,11 @@ Solid Node documentation
    why-solid-node
    quickstart
    using-solid-node
+   api-reference
    status-and-roadmap
    contributing
+
+Indices and tables
+==================
+* :ref:`genindex`
+* :ref:`search`

docs/status-and-roadmap.rst

@@ -5,12 +5,14 @@
 Project status
 ==============
 
-This project has been developed and maintained by a single person so far, and as it is, it's pretty usable. It can already solve real bottlenecks in mechanical project development. It's still a bit far from 1.0 version, but the **current node API should not change** until there.
+This project has been developed and maintained by a single person so far, and as it is, it's pretty usable. It can already solve real bottlenecks in mechanical project development. It's still a bit far from 1.0 version, but the **current node API should not change** until there, so you're invited to use it in your next 3D printable Free Software project.
 
 Roadmap
 =======
 
-  * Improve the web viewer with workplanes, rulers, camera angles, animation control, etc
-  * A "dist" command that packs the project into a distributable with source and builds
-  * A "publish" command that creates a static website with docstrings, viewer, source and build downloads
+  * A command to pack the project into a distributable with source and builds
+  * Improve the web viewer with workplanes, rulers, camera angles, animation control, a test runner
+  * A command to create a static website with docstrings, the viewer, source and build downloads
+  * A FlexibleNode class to create objects that change shape over time, with keyframes for animation
+  * A OpenJScadNode class to support OpenJScad.
   * Separate the watcher and builder internal processes to recover from errors

docs/why-solid-node.rst

@@ -3,8 +3,8 @@ Why Solid Node
 
 When designing a mechanical project with Free Software, there are some technologies available that allow parametric design, using source code to create solid structures. There's OpenScad, which uses it's own scripting language, and on top of it there is Solid Python, which allows modelling for OpenScad using Python language. Python also has CadQuery, which is more powerful and flexible for complex designs, but has a steeper learning curve. When picking which technology to use, one should consider the libraries available, and a complex project might need to assemble pieces that come from different libraries. Openscad has a native animation system that allows developing projects with moving parts, but it soon gets very slow as project grows.
 
-Solid Node come as a framework to join all these underlying technologies together. It's inspired by a web development culture, which uses frameworks like Django, React and Angular, that monitors filesystem for changes and shows the result automatically. Solid Node proposes an architecture that allows building of pieces as they change, being able to handle a lot of moving parts.
+Solid Node come as a framework to join all these underlying technologies together and solve performance bottlenecks. It's inspired by a web development culture, which uses frameworks like Django, React and Angular, that monitors filesystem for changes and shows results automatically. Solid Node proposes an architecture that allows building of pieces as they change, being able to handle a lot of moving parts.
 
-Solid Node also provides testing capabilities. Mechanical projects can generate a lot of garbage from experimentation, and this can be substantially reduced by being able to logically test connections between components before producing anything.
+Solid Node also provides testing capabilities. Prototyping can take a lot of time and generate a lot of garbage, and this can be substantially reduced by being able to logically test connections between components before producing anything.
 
 Solid Node is Free Software, released under the AGPLv3. This mean that any project using it is bound to the AGPLv3. As digital manufacturing technologies, like 3D printing, become popular, distribution of source code can greatly increase goods lifetime and reduce waste generation. Free Software modeling and source code distribution should become an industry standard, and this project is one more step towards that.

solid_node/core/builder.py

@@ -25,6 +25,7 @@ def __init__(self, path):
         self.observer = Observer()
 
     def start(self):
+        """Start the rendering process and wait for a file to change, then exits"""
         task = self._start()
         self.loop = asyncio.get_event_loop()
         self.loop.run_until_complete(task)
@@ -69,16 +70,10 @@ async def _start(self):
         await self.file_changed
         sys.exit(0)
 
-    async def execute_refactor(self, request):
-        try:
-            request.refactor()
-            sys.exit(0)
-        except Exception as e:
-            error_message = traceback.format_exc()
-            logger.error(error_message)
-            await self.report_error(f"Could not execute refactor\n\n{error_message}")
-
     async def generate_stl(self):
+        """Trigger the stl generation on the root node, that will recursively render
+        stls in all nodes. If in the middle a STL is built, the builder process
+        exits to be restarted."""
         try:
             self.node.trigger_stl()
             return
@@ -97,7 +92,21 @@ async def report_error(self, error_message):
         sys.exit(0)
 
     def on_modified(self, event):
+        """Called when a file is modified, sets the result of the awaiting future
+        for the process to exit"""
         if event.is_directory:
             return
         logging.info(f'{event.src_path} changed, reloading')
         self.loop.call_soon_threadsafe(self.file_changed.set_result, True)
+
+    async def execute_refactor(self, request):
+        """Experimental: refactor requests are special exceptions injected in scope
+        that trigger the builder to refactor nodes. Make sure you commit your changes
+        before using it."""
+        try:
+            request.refactor()
+            sys.exit(0)
+        except Exception as e:
+            error_message = traceback.format_exc()
+            logger.error(error_message)
+            await self.report_error(f"Could not execute refactor\n\n{error_message}")

solid_node/node/adapters/cadquery.py

@@ -24,6 +24,7 @@ class CadQueryNode(LeafNode, metaclass=CheckCQEditor):
     namespace = 'cadquery.cq'
 
     def as_scad(self, rendered):
+        """Export the model to STL and returns a scad code to render it"""
         cq.exporters.export(rendered, self.stl_file, 'STL')
         os.utime(self.stl_file, (time.time(), self.mtime))
         return import_stl(self.local_stl)

solid_node/node/adapters/openscad.py

@@ -1,8 +1,6 @@
 import os
-import re
 import tempfile
 import inspect
-from subprocess import Popen
 from solid2 import scad_render, import_scad
 from solid2.core.parse_scad import get_scad_file_as_dict
 from solid2.core.utils import resolve_scad_filename
@@ -17,6 +15,16 @@ class OpenScadNode(LeafNode):
     namespace = 'solid2.core.object_factory'
 
     def __init__(self, source, *args, name=None, **kwargs):
+        """Receives a source code and arguments, imports an OpenScad module from
+        the source and renders it using *args and **kwargs
+        The OpenScad code must implement a module with same name as file
+
+        Args:
+           source (str): The .scad source code, in the same folder as the python file
+           *args: will be passed as arguments to the OpenScad module
+           name keyword argument: the name of this node, defaul to name of the class
+           **kwargs: will be passed as keyword arguments to the openscad module
+        """
         frame = inspect.currentframe().f_back
         caller = frame.f_globals.get('__file__')
         basedir = os.path.dirname(caller)
@@ -30,9 +38,11 @@ def __init__(self, source, *args, name=None, **kwargs):
         super().__init__(*args, name=name, **kwargs)
 
     def get_source_file(self):
+        """Gets the openscad source code path"""
         return self.openscad_source
 
     def render(self):
+        """Imports the OpenScad source code and renders into a solid2 object"""
         filename = resolve_scad_filename(self.openscad_source)
         scad = get_scad_file_as_dict(filename)
         try:
@@ -43,10 +53,12 @@ def render(self):
         return rendered
 
     def as_scad(self, rendered):
+        """Returns the rendered argument (do nothing)"""
         return rendered
 
     @property
     def scad_code(self):
+        """The contents of the code, plus a module call"""
         rendered = scad_render(self.model)
         module_call = rendered.strip().split('\n')[-1]
         return f'{self.openscad_code}\n\n{module_call}'

solid_node/node/adapters/solid2.py

@@ -18,9 +18,12 @@ class Solid2Node(LeafNode):
     namespace = 'solid2'
 
     def as_scad(self, rendered):
+        """Doesn't do anything, as solid2 objects are already OpenScad objects"""
         return rendered
 
     def as_number(self, n):
+        """Receives a solid2 function result and calculates its number.
+        uses an openscad process internally to do the calculation."""
         if type(n).__module__.startswith('solid2'):
             # This is very clumsy, but it works. Trimesh cannot load
             # translated / rotated mesh, and transforming meshes after loading

solid_node/node/assembly.py

@@ -5,7 +5,8 @@
 class AssemblyNode(InternalNode):
     """
     Represents a collection of components that can be moved relative to each other.
-    This is an internal node that can contain instances of LeafNode or other internal nodes.
+    This is an internal node that can contain instances of LeafNode or other
+    internal nodes.
     The render method of this class returns a list of its child nodes.
     """
 

solid_node/node/base.py

@@ -41,6 +41,7 @@ class AbstractBaseNode:
     children = tuple()
 
     # Set to false to render scad directly instead of stls
+    # Only works in openscad viewer
     optimize = True
 
     def __init__(self, *args, name=None, **kwargs):
@@ -111,6 +112,7 @@ def __init__(self, *args, name=None, **kwargs):
         self._make_build_dirs()
 
     def get_source_file(self):
+        """Finds the source file of this node"""
         return inspect.getfile(self.__class__)
 
     @property