FlowProject.operation documentation doesn't show up in signac-flow API docs home page

[kidrahahjo]

Description

The "description" of FlowProject.operation doesn't show up in https://docs.signac.io/projects/flow/en/latest/api.html. Is there a reason for this?

[cbkerr]

It's pulling the information from OperationRegister, but I'm not sure why.

[vyasr]

I can explain why this is probably happening, but I'm not immediately sure how to fix it (Sphinx at this level of complexity is always a bit of trial and error for me):

1. The FlowProject has a custom metaclass called FlowProjectClass that defines a bunch of attributes on every subclass of FlowProject. The metaclass is necessary because we define workflows as subclasses of FlowProject rather than instances of FlowProject. In other words, we need the metaclasses so that e.g. operations registered to one project don't get registered to all subclasses of FlowProject:

class Project1(FlowProject):
    pass

class Project2(FlowProject):
    pass

# We don't want `op1` in `Project2`
@Project1.operation
def op1(job):
    pass

# We don't want `op2` in `Project1`
@Project2.operation
def op2(job):
    pass

2. Specifically, the pre- and postcondition decorators as well as the operation decorator are created once for each subclass so that the conditions/operations are registered to the appropriate subclass.
3. While the pre and post decorators are classes (for example, the precondition setup function returns the locally defined pre class), the operation decorator is also defining a class locally but it then returns an instance of that class.

My guess is that item (3) is the problem: since FlowProject.operation is an instance of the OperationRegister rather than the class itself, Sphinx's autosummary plugin is having trouble pulling the docstring. The class vs instance difference arises because of differences in how we use the decorators: pre- and postconditions always have an argument (the condition), so we always instantiate the class, whereas the operation decorator's argument (which allows the user to specify a different name for the operation) is only used sparingly. In principle we could probably rework the implementation to bring the conditions/operations into greater alignment, but hopefully there is a simpler solution to getting the docstring to show up.