Adding Sphinx doctest to our CI

[marcus7070]

I'm trying to write up this example into our docs. If I simply cut and paste code into the RST I'm concerned about it going out of date and I'll forget about it.

So I'd like to use Sphinx's doctest directive. I think doctest could also be applied to other examples in the docs, like

• https://cadquery.readthedocs.io/en/latest/quickstart.html#exporting
• https://cadquery.readthedocs.io/en/latest/primer.html#assemblies
• https://cadquery.readthedocs.io/en/latest/assy.html#final-result

https://cadquery.readthedocs.io/en/latest/importexport.html in particular lists a lot of arguments, it would be nice to inspect function signatures with doctest and make sure they match. You can hide the test input and output, so the HTML would still look the same.

1. Should we add doctest to our CI?
2. I don't think Sphinx doctest fits neatly in any of our current pipelines, should we make a new one for doctest?
3. I'm most comfortable with Github's own actions/CI/pipelines/whatever it's called today. Should I write a workflow for this?

[adam-urbanczyk]

Currently all the examples that are rendered in the docs via the cadquery directive are tested in the CI (

cadquery/tests/test_examples.py

Line 59 in 4c5816d

def test_example(code, path):

). What would doctest achieve on top of this? Whatever we do, I don't think that you need another pipeline - it is better to extend the tests.

[marcus7070]

I'd forgot about that test_example bit, thanks for reminding me.

Here is what I was thinking with the bit I'm writing now. If we do another change like #678 then this would fail a test and I'd update it.

doc/primer.rst:

To demonstrate the above concepts, we can define more detailed string representations for the
Workplane, Plane and CQContext classes and patch them to the CadQuery classes.

.. testcode:: introspectExample

    import cadquery as cq


    def _ctx_str(self):
        return (
            f"CQContext object with id: {id(self)}\n"
            + f"    pendingWires: {self.pendingWires}\n"
            + f"    pendingEdges: {self.pendingEdges}\n"
            + f"    tags: {self.tags}\n"
        )


    cq.cq.CQContext.__str__ = _ctx_str


    def _plane_str(self):
        return (
            f"Plane with id: {id(self)}\n"
            + f"    origin: {self.origin.toTuple()}\n"
            + f"    z direction: {self.zDir.toTuple()}"
        )


    cq.occ_impl.geom.Plane.__str__ = _plane_str


    def _wp_str(self):
        out = f"Workplane with id: {id(self)}\n"
        if self.parent is None:
            out += "  no parent\n"
        else:
            out += f"  parent: {id(self.parent)}\n"
        out += f"  plane: {self.plane}\n"
        out += f"  objects: {self.objects}\n"
        out += f"  modelling context: {self.ctx}"
        return out


    cq.Workplane.__str__ = _wp_str


Now we can make a simple part and examine the Workplane and CQContext objects at each step.

The start of our chain of calls is:


.. testcode:: introspectExample

    part = cq.Workplane()
    print(part)


Which produces the output:


.. testoutput:: introspectExample
    :options: +NORMALIZE_WHITESPACE
    :hide:

    Workplane with id: ...
      no parent
      plane: Plane with id: ...
        origin: (0.0, 0.0, 0.0)
        z direction: (0.0, 0.0, 1.0)
      objects: []
      modelling context: CQContext object with id: ...
        pendingWires: []
        pendingEdges: []
        tags: {}



::

    Workplane object at 0x7f2f7ca5c760:
      no parent
      plane: Plane object at 0x7f2f7ca5c850:
        origin: (0.0, 0.0, 0.0)
        z direction: (0.0, 0.0, 1.0)

      objects: []
      modelling context: CQContext object at 0x7f2f7ca5c730:
        pendingWires: []
        pendingEdges: []
        tags: {}


This is simply an empty Workplane. Being the first Workplane in the stack, it does not have a
parent. The plane attribute contains a Plane object that describes the XY plane.

As an aside, the testoutput directive spits out the pattern it's looking for (ellipsis and all) rather that the test output, so I have to hide it and put the output (including those variable references) in as a regular code block.

What would doctest achieve on top of this? Whatever we do, I don't think that you need another pipeline - it is better to extend the tests.

Yes, I can achieve the same effect as doctest in a regular pytest test and have a comment explaining the docs need to be updated whenever the test fails. The advantage to doctest is those tests are right next to the example that needs to be fixed, making it easier to keep in sync. But it's not worth adding all the doctest overhead for this one test. I'll reopen this if I find enough other places in the docs that would benefit.