Merge branch 'doc_improvements' into dev

Author: drayde

dist/cadscript-0.5.3-py3-none-any.whl

@@ -12,6 +12,7 @@
 from cadquery.occ_impl.assembly import toJSON
 from cadquery.occ_impl.jupyter_tools import DEFAULT_COLOR
 from docutils.parsers.rst import directives
+from sphinx.application import Sphinx
 
 from cadquery.cq_directive import cq_directive_vtk, template_vtk, rendering_code
 
@@ -45,6 +46,8 @@
 
 """
 
+theapp = None
+
 
 class cadscript_directive(cq_directive_vtk):
 
@@ -90,7 +93,7 @@ def run(self):
                 pre_script, script, text = self.get_source_file(content, options.get("steps", None), "text_from_comment" in options)
         else:
             # else use inline code
-            script = "\n".join(script)        
+            script = "\n".join(script)
 
         # add the prefix and postfix
         plot_code = prefix + "\n" + pre_script + "\n" + script + "\n" + postfix.format(result_var=result_var)
@@ -106,7 +109,7 @@ def run(self):
     def get_source_file(self, content, steps, text_from_comment):
 
         content = re.sub(r'^cadscript.show\(.*$', '', content, flags=re.MULTILINE)  # remove show() calls
-        text = ""
+        text = []
         pre_script = []
         content = content + "\n"  # fix problem with last line
         ellipsis = False
@@ -134,13 +137,15 @@ def get_source_file(self, content, steps, text_from_comment):
         if text_from_comment:
             # extract the text from the comment
             newscript = []
-            last_comment = ""
+            last_comment = []
             for part in script:
-                last_comment = ""
+                last_comment = []
                 new_part = ""
                 for line in part.split("\n")[:-1]:  # skip last empty item with [:-1]
-                    if line.startswith("#"):
-                        last_comment += line[1:].strip() + " "
+                    if line.startswith("# "):
+                        last_comment.append(line[2:])
+                    elif line.startswith("#"):
+                        last_comment.append(line[1:])
                     else:
                         new_part += line + "\n"
                 newscript.append(new_part)
@@ -160,23 +165,24 @@ def generate_output(self, plot_code, text, script, options):
         lines = []
 
         if len(text):
-            lines.extend(["", text, ""])
-
-        if "side-by-side" in options:
-            lines.append(".. raw:: html")
             lines.append("")
-            lines.append("    <div class=\"side-by-side\"><div class=\"leftside\">")
+            lines.extend(text)
             lines.append("")
 
-        lines.extend(["", "::", ""])
-        lines.extend(["    %s" % row.rstrip() for row in script.split("\n")])
+        lines.append(".. raw:: html")
         lines.append("")
-
         if "side-by-side" in options:
-            lines.append(".. raw:: html")
-            lines.append("")
-            lines.append("    </div>")
-            lines.append("")
+            lines.append("    <div class=\"cq-side-by-side\"><div class=\"leftside\">")
+        else:
+            lines.append("    <div class=\"cq-top-bottom\"><div class=\"cq-top\">")
+        lines.append("")
+
+        lines.extend(self.generate_code_block(script))
+
+        lines.append(".. raw:: html")
+        lines.append("")
+        lines.append("    </div>")
+        lines.append("")
 
         try:
             result = cqgi.parse(plot_code).build()
@@ -210,11 +216,10 @@ def generate_output(self, plot_code, text, script, options):
             traceback.print_exc()
             assy = Assembly(Compound.makeText("CQGI error", 10, 5))
 
-        if "side-by-side" in options:
-            lines.append("")
-            lines.append(".. raw:: html")
-            lines.append("")
-            lines.append("    </div>")
+        lines.append("")
+        lines.append(".. raw:: html")
+        lines.append("")
+        lines.append("    </div>")
         lines.append("")
 
         return lines
@@ -290,6 +295,74 @@ def render_image(self, assy, options):
         ).splitlines()
 
 
+    def generate_code_block(self, code):
+        """
+        Generate a code block with links to the documentation for method calls.
+        """
+        highlighter = theapp.builder.highlighter
+
+        body_prefixes = ["body", "box", "result", "extr"]
+        sketch_prefixes = ["sketch", "s"]
+        cadscript_prefixes = ["cad", "cadscript"]
+
+        # Regular expression to find method calls like obj.method(
+        # in html the string looks like
+        # <span class="n">cadscript</span><span class="o">.</span><span class="n">make_box</span><span class="p">(
+
+        method_call_pattern = re.compile(
+            r'\<span\s+class\=\"n\"\>'  # <span class="n">
+            r'\s*(\w+)\s*'              # methodName
+            r'\<\/span\>\s*'            # </span>
+            r'\<span\s+class\=\"o\"\>'  # <span class="o">
+            r'\s*\.\s*'                 # .
+            r'\<\/span\>\s*'            # </span>
+            r'\<span\s+class\=\"n\"\>'  # <span class="n">
+            r'\s*(\w+)\s*'              # methodName
+            r'\<\/span\>\s*'            # </span>
+            r'\<span\s+class\=\"p\"\>'  # <span class="p">
+            r'\s*\('                    # (
+        )
+
+        # Function to replace method calls with links if they are documented
+        # class="n">(\w+)\.(\w+)\((.*?)\)')
+        def replace_method_call(match):
+            obj_name, method_name = match.groups()
+
+            # Determine which document to link based on the prefix
+            # todo: could be done by examining env.domaindata['py']['objects']
+            if any(obj_name.startswith(prefix) for prefix in body_prefixes):
+                link_target = f'ref_body.html#cadscript.Body.{method_name}'
+            elif any(obj_name.startswith(prefix) for prefix in sketch_prefixes):
+                link_target = f'ref_sketch.html#cadscript.Sketch.{method_name}'
+            elif any(obj_name.startswith(prefix) for prefix in cadscript_prefixes):
+                link_target = f'ref_module_functions.html#cadscript.{method_name}'
+            else:
+                return match.group(0)  # No replacement if prefix does not match
+
+            link = (
+                f'<span class="n">{obj_name}</span>'
+                f'<span class="o">.</span>'
+                f'<span class="n"><a class="codelink" href="{link_target}">{method_name}</a></span>'
+                f'<span class="p">('
+            )
+            return link
+
+
+        # Use Sphinx highlighter to generate HTML
+        highlighted_code = highlighter.highlight_block(code, 'python')
+
+        # Replace method calls with links
+        linked_code = method_call_pattern.sub(replace_method_call, highlighted_code)
+
+        lines = []
+        lines.append(".. raw:: html")
+        lines.append("")
+        lines.extend(["    %s" % line.rstrip() for line in linked_code.split("\n")])
+        lines.append("")
+
+        return lines
+
+
 
 class cadscript_auto_directive(cadscript_directive):
 
@@ -351,6 +424,12 @@ def setup(app):
     app.add_js_file("vtk.js")
     app.add_js_file(None, body=rendering_code)
 
+    app.connect("builder-inited", remember_app)
+
+
+def remember_app(app: Sphinx) -> None:
+    global theapp  # bad hack to remember the app object
+    theapp = app
 
 
 if __name__ == "__main__":
@@ -367,5 +446,5 @@ def setup(app):
         setup(app)
     except Exception:
         pass
-    pre_script, script, text = c.get_source_file(open(c.get_file('./examples/bracket.py')).read(), "2-14", True)
+    pre_script, script, text = c.get_source_file(open(c.get_file('./examples/bracket.py')).read(), "2", True)
     pre_script, script, text = c.get_source_file(open(c.get_file('./examples/getting_started.py')).read(), None, None)

dist/cadscript-0.5.3.tar.gz

@@ -1,3 +1,5 @@
+/* cq render right of code */
+
 div.leftside {
   width: 43%;
   padding: 0px 3px 0px 0px;
@@ -9,11 +11,33 @@ div.rightside {
   /* float: right; */
 }
 
-div.side-by-side {  
+div.cq-side-by-side {  
   padding: 1px;
   border: 1px solid #ccc;
 } 
 
+/* cq render after code */
+
+
+div.cq-top > div.highlight { /* code block */
+  margin-bottom: 0;
+  border-left: 5px solid #ccc;
+}
+
+div.cq-top-bottom > div.cq { /* render */
+  padding-top: 5px;
+  padding-left: 10px;
+  margin-bottom: 20px;
+  border-left: 5px solid #ccc;
+}
+
+/* better table formatting */
 table.docutils td p {
   text-wrap: wrap;
+}
+
+/* links in code */
+a.codelink, a.codelink:visited {
+  color: #0000FF;
+  text-decoration: underline #C0C0FF;
 }

docs/ext/cadscript_directives.py

@@ -27,6 +27,7 @@
     'ext.cadscript_directives',
 ]
 
+
 autodoc_default_options = {
     'member-order': 'bysource',
     # 'special-members': '__init__',
@@ -48,3 +49,18 @@
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ["_static"]
+
+def skip_member(app, what, name, obj, skip, options):
+    # List of menbers (methods, classes, ...) to exclude
+    exclude = ["CqMode"]
+    
+    # Exclude if the name is in the exclude list 
+    if name in exclude:
+        return True
+    # Exclude if starts with an underscore
+    if name.startswith("_"):
+        return True
+    return skip
+
+def setup(app):
+    app.connect("autodoc-skip-member", skip_member)

docs/source/_static/cadscript.css

@@ -41,15 +41,6 @@ Rectangles
 
 
 
-See also
-
-.. hlist::
-
-    * :py:meth:`cadscript.make_box` 
-    * :py:meth:`Sketch.add_rect` 
-
-
-
 Circles
 -------
 
@@ -74,10 +65,4 @@ Circles
     sketch.add_circle(d=40, pos=(20, 10))
 
 
-See also
-
-.. hlist::
-
-    * :py:meth:`cadscript.make_box` 
-    * :py:meth:`Sketch.add_circle` 
 

docs/source/conf.py

@@ -52,18 +52,6 @@ Finally, we place the sketch on the top face of our object, rotate it 45 degrees
 .. cadscript:: 
     :source: ../examples/getting_started.py
 
-.. topic:: Api References
-
-    .. hlist::
-
-        * :py:meth:`cadscript.make_box` 
-        * :py:meth:`Body.fillet` 
-        * :py:meth:`Body.chamfer` 
-        * :py:meth:`cadscript.make_sketch`    
-        * :py:meth:`Sketch.add_circle` 
-        * :py:meth:`Sketch.add_rect` 
-        * :py:meth:`Body.cut_extrude` 
-
 
 Second Example
 --------------

docs/source/doc_sketch_examples.rst

@@ -2,6 +2,8 @@
 # This file is part of Cadscript
 # SPDX-License-Identifier: Apache-2.0
 
+# example script also used to generate documentation
+
 # this is used by the documentation generation
 # DOCSTEP: 2,sketch1
 # DOCSTEP: ...3,sketch1
@@ -21,7 +23,13 @@
 import cadscript
 
 # STEP 2
-# Let's start with a sketch.
+# In this example we build a complex object by
+#
+# - creating two sketches
+# - extruding them
+# - intersecting the two extrusions
+#
+# Let's start with the first sketch.
 # We add a rectangle with width 70 and height 30, centered at the origin.
 sketch1 = cadscript.make_sketch()
 sketch1.add_rect(70, 30)
@@ -53,7 +61,7 @@
 sketch1.cut_circle(d=16, pos=(50, 0))
 
 # STEP 8
-# Make a new sketch, add a rectangle and a circle.
+# now we create the second sketch. We start with a rectangle and a circle.
 sketch2 = cadscript.make_sketch()
 sketch2.add_rect(70, 5, center=False)
 sketch2.add_circle(d=26, pos=(0, 10))
@@ -92,5 +100,4 @@
 
 # STEP 14 dummy step to show whole script in documentation
 # The complete script looks like this:
-
-cadscript.show(result)
+cadscript.show(result)