Docs reorganization

docs/advanced.rst

@@ -0,0 +1,11 @@
+###############
+Advanced Topics
+###############
+
+.. toctree::
+    :maxdepth: 2
+
+    assemblies.rst
+    center.rst
+    custom.rst
+    debugging_logging.rst

docs/advantages.rst

@@ -1,13 +1,9 @@
-##########
-Advantages
-##########
-
 As mentioned previously, the most significant advantage is that build123d is more pythonic.
 Specifically:
 
-*******************************
 Standard Python Context Manager
-*******************************
+===============================
+
 The creation of standard instance variables, looping and other normal python operations
 is enabled by the replacement of method chaining (fluent programming) with a standard
 python context manager.
@@ -40,9 +36,9 @@ statement anywhere in the code without impacting functionality. Simple python
 `for` loops can be used to repetitively create objects instead of forcing users
 into using more complex `lambda` and `iter` operations.
 
-********************
 Instantiated Objects
-********************
+====================
+
 Each object and operation is now a class instantiation that interacts with the
 active context implicitly for the user. These instantiations can be assigned to
 an instance variable as with standard python programming for direct use.
@@ -54,9 +50,9 @@ an instance variable as with standard python programming for direct use.
         print(r.Area())
         ...
 
-*********
 Operators
-*********
+=========
+
 New operators have been created to extract information from objects created previously
 in the code. The `@` operator extracts the position along an Edge or Wire while the
 `%` operator extracts the tangent along an Edge or Wire. The position parameter are float
@@ -75,9 +71,8 @@ features to these points without knowing their numeric values.
         Spline(l5 @ 1, l6 @ 0, tangents=(l5 % 1, l6 % 0))
 
 
-**********************
 Last Operation Objects
-**********************
+======================
 All of the `vertices()`, `edges()`, `faces()`, and `solids()` methods of the builders
 can either return all of the objects requested or just the objects changed during the
 last operation. This allows the user to easily access features for further refinement,
@@ -86,25 +81,24 @@ by the last operation and fillets them. Such a selection would be quite difficul
 otherwise.
 
 .. literalinclude:: ../examples/intersecting_pipes.py
+    :lines: 29, 37-48
 
 
-**********
 Extensions
-**********
+==========
 Extending build123d is relatively simple in that custom objects or operations
 can be created as new classes without the need to monkey patch any of the
 core functionality. These new classes will be seen in IDEs which is not
 possible with monkey patching the core CadQuery classes.
 
-*****
 Enums
-*****
+=====
+
 All `Literal` strings have been replaced with `Enum` which allows IDEs to
 prompt users for valid options without having to refer to documentation.
 
-***************************
 Selectors replaced by Lists
-***************************
+===========================
 String based selectors have been replaced with standard python filters and
 sorting which opens up the fully functionality of python list functionality.
 To aid the user, common operations have been optimized as shown here along with

docs/build_part.rst

@@ -0,0 +1,3 @@
+#########
+BuildPart
+#########

docs/build_sketch.rst

@@ -0,0 +1,3 @@
+###########
+BuildSketch
+###########

docs/builders.rst

@@ -0,0 +1,12 @@
+########
+Builders
+########
+
+The following sections describe each of the build123d stateful context builders.
+
+.. toctree::
+    :maxdepth: 2
+
+    build_line.rst
+    build_sketch.rst
+    build_part.rst

docs/center.rst

@@ -0,0 +1,3 @@
+##################
+CAD Object Centers
+##################

docs/conf.py

@@ -48,6 +48,7 @@ extensions = [
     "sphinx.ext.inheritance_diagram",
     "sphinx.ext.viewcode",
     "sphinx_design",
+    "sphinx_copybutton",
 ]
 
 # Napoleon settings

docs/custom.rst

@@ -0,0 +1,3 @@
+###################################
+Custom Builder Objects & Operations
+###################################

docs/debugging_logging.rst

@@ -0,0 +1,3 @@
+###################
+Debugging & Logging
+###################

docs/index.rst

@@ -89,13 +89,12 @@ Table Of Contents
 
     introduction.rst
     installation.rst
-    cheat_sheet.rst
-    key_concepts.rst
-    buildline.rst
-    assemblies.rst
+    introductory_examples.rst
     tutorials.rst
+    builders.rst
+    advanced.rst
+    cheat_sheet.rst
     external.rst
-    advantages.rst
     builder_api_reference.rst
     direct_api_reference.rst
 

docs/introduction.rst

@@ -2,13 +2,16 @@
 Introduction
 ############
 
+***********
+Key Aspects
+***********
+
 The following sections describe some of the key aspects of build123d and illustrate
 why one might choose this open source system over proprietary options like SolidWorks,
 OnShape, Fusion 360, or even other open source systems like Blender, or OpenSCAD.
 
-****************************************
 Boundary Representation (BREP) Modelling
-****************************************
+========================================
 
 Boundary representation (BREP) and mesh-based CAD systems are both used to
 create and manipulate 3D models, but they differ in the way they represent and
@@ -50,9 +53,8 @@ Advantages of Mesh-based CAD systems (e.g. Blender, OpenSCAD):
   large datasets such as point clouds, as they can be easily converted into a mesh
   representation.
 
-********************
 Parameterized Models
-********************
+====================
 
 Parametrized CAD systems are more effective than non-parametric CAD systems in
 several ways:
@@ -83,9 +85,8 @@ systems because they provide a more efficient and flexible way to create and
 modify designs, and can be easily integrated into the design, manufacturing, and
 documentation process.
 
-***************************
 Python Programming Language
-***************************
+===========================
 
 Python is a popular, high-level programming language that has several advantages
 over other programming languages:
@@ -118,9 +119,8 @@ over other programming languages:
   connecting to web servers, reading and modifying files, and connecting to
   databases.
 
-********************
 Open Source Software
-********************
+====================
 
 Open source and proprietary software systems are different in several ways: B
 Licensing: Open source software is licensed in a way that allows users to view,
@@ -156,9 +156,8 @@ software may have a larger community of users who can provide support, while
 proprietary software may have a smaller community and relies on the company for
 support.
 
-***************************
 Source Code Control Systems
-***************************
+===========================
 
 Most GUI based CAD systems provide version control systems which represent the
 CAD design and its history. They allows developers to see changes made to the design
@@ -196,9 +195,8 @@ easier to use, while source code control systems like Git offer more flexibility
 and control over the code. Both can be used to achieve the same goal, but they
 cater to different types of users and use cases.
 
-*****************
 Automated Testing
-*****************
+=================
 
 Users of source based CAD systems can benefit from automated testing which improves
 their source code by:
@@ -234,10 +232,8 @@ process, it helps to improve the quality of the code by detecting bugs early,
 documenting code behavior, and reducing the cost of maintaining and updating the
 code.
 
-
-***********************
 Automated Documentation
-***********************
+=======================
 
 The Sphinx automated documentation system was used to create the page you are
 reading now and can be used for user design documentation as well.  Such systems
@@ -273,3 +269,15 @@ comments. They save time and effort compared to manual documentation, and can be
 customized to match the look and feel of your company's documentation. They also
 provide multiple output formats, support for multiple languages and can be
 integrated with code management tools.
+
+**********************
+Build123d Key Concepts
+**********************
+
+.. include:: key_concepts.rst
+
+************************
+Advantages Over CadQuery
+************************
+
+.. include:: advantages.rst

docs/introductory_examples.rst

@@ -1,6 +1,6 @@
-#################
-General Tutorials
-#################
+#####################
+Introductory Examples
+#####################
 
 The examples on this page can help you learn how to build objects with Build123d, and are intended as a general overview of Build123d.
 

docs/key_concepts.rst

@@ -1,12 +1,7 @@
-########
-Concepts
-########
-
 The following key concepts will help new users understand build123d quickly.
 
-********
 Builders
-********
+========
 
 The three builders, ``BuildLine``, ``BuildSketch``, and ``BuildPart`` are tools to create
 new objects - not the objects themselves. Each of the objects and operations applicable
@@ -39,9 +34,33 @@ instance variable. For example:
 
     show_object(my_line.line)
 
-******************
+Implicit Builder Instance Variables
+===================================
+
+One might expect to have to reference a builder's instance variable when using
+objects or operations that impact that builder like this:
+
+.. code-block:: python
+
+    with BuildPart() as part_builder:
+        Box(part_builder, 10,10,10)
+
+Instead, build123d determines from the scope of the object or operation which
+builder it applies to thus eliminating the need for the user to provide this
+information - as follows:
+
+.. code-block:: python
+
+    with BuildPart() as part_builder:
+        Box(10,10,10)
+        with BuildSketch() as sketch_builder:
+            Circle(2)
+
+In this example, ``Box`` is in the scope of ``part_builder`` while ``Circle``
+is in the scope of ``sketch_builder``.
+
 Workplane Contexts
-******************
+==================
 
 As build123d is a 3D CAD package one must be able to position objects anywhere. As one
 frequently will work in the same plane for a sequence of operations, a workplane is used
@@ -92,9 +111,8 @@ This is the result:
 .. image:: boxes_on_faces.svg
   :align: center
 
-****************
 Location Context
-****************
+================
 
 When positioning objects or operations within a builder Location Contexts are used.  These
 function in a very similar was to the builders in that they create a context where one or
@@ -140,9 +158,8 @@ to retrieve the global locations relative to the current workplane(s) as follows
     Location(p=(0.50,0.00,0.50), o=(90.00,-0.00,0.00))
 
 
-****************
 Operation Inputs
-****************
+================
 
 When one is operating on an existing object, e.g. adding a fillet to a part,
 a sequence of objects is often required. A python sequence of objects is
@@ -172,9 +189,9 @@ followed by a fillet radius as follows:
 Here the list of edges from the last operation of the ``pipes`` builder are converted
 to a sequence and a radius is provided as a keyword argument.
 
-*****************
 Combination Modes
-*****************
+=================
+
 Almost all objects or operations have a ``mode`` parameter which is defined by the
 ``Mode`` Enum class as follows:
 
@@ -202,15 +219,13 @@ a volume from the part under normal circumstances. However, the ``mode`` used in
 the ``Hole`` classes can be specified as ``Mode.ADD`` or ``Mode.INTERSECT`` to
 help in inspection or debugging.
 
-*********
 Selectors
-*********
+=========
 
 .. include:: selectors.rst
 
-**********************************
 Using Locations & Rotating Objects
-**********************************
+==================================
 
 build123d stores points (to be specific ``Locations``) internally to be used as
 positions for the placement of new objects.  By default, a single location
@@ -251,9 +266,8 @@ combine rotations with the `*` operator like this:
     ``Rotation`` is a subclass of ``Location`` and therefore will also accept
     a position component.
 
-*************************
 Builder's Pending Objects
-*************************
+=========================
 
 When a builder exits, it will push the object created back to its parent if
 there was one.  Here is an example:

docs/tutorials.rst

@@ -9,7 +9,6 @@ as later tutorials build on the concepts introduced in earlier ones.
 .. toctree::
     :maxdepth: 2
 
-    tutorial_general.rst
     tutorial_selectors.rst
     tutorial_lego.rst
     tutorial_joints.rst