Adding a cq_test directive

[marcus7070]

Say I write the following in the docs:

The ``tag`` method is unusual for a Workplane method in that it returns the same Workplane object, not a new one.

Immediately after that I would like to write a test like

a = cq.Workplane()
b = a.tag("_")
assert a == b

Now if that test ever fails, I can fix my statement in the docs that I have long since forgot because I have the attention span of a caffeinated chipmunk.

If we created a directive in docs/cq_directive called cq_test that instructed Sphinx to just do nothing with the content (ie. no output in docs), then we could collect them during testing like we currently do for the cadquery directive here:

cadquery/tests/test_examples.py

Line 39 in 3cb7237

directives.register_directive("cadquery", dummy_cq_directive)

by adding the line:

directives.register_directive("cq_test", dummy_cq_directive)

and now my RST would be:

The ``tag`` method is unusual for a Workplane method in that it returns the same Workplane object, not a new one.

.. cq_test::

    a = cq.Workplane()
    b = a.tag("_")
    assert a == b

and pytest would run that test.

Does all that sound good?

[adam-urbanczyk]

IMO you'll make the raw docs completely unreadable. Is there a specific problem you are trying to solve here?

[marcus7070]

There is a specific problem although it's not an important one. It's that internals example again: https://gist.github.com/marcus7070/271e2ec67d1ff548341a4820868be0c2 and I'm concerned about it going out of date. The test above would be one of the ones I implement.

Can you think of a cleaner way to do the above example?

It's not important, I think I'll just do this internals example as simple text for now.

[adam-urbanczyk]

Maybe insert it as a file (and ignore some assert lines)