docs: expand the reference documentation #169
Conversation
Co-authored-by: PietroPasotti <[email protected]>
|
Hi @tmihoc ! Would you mind giving this a review when you have some time? Thanks! |
scenario/__init__.py
Outdated
|
|
||
| """Charm state-transition testing SDK for Operator Framework charms. | ||
|
|
||
| Write unit tests that declaratively define the Juju state all at once, define |
There was a problem hiding this comment.
So we promote scenario as another way to do unit tests, then? We should sync with Charmcraft to make sure their profiles create a directory structure for tests that is aligned.
There was a problem hiding this comment.
We're (imminently) going to be promoting Scenario as the preferred way to do unit tests. I also tried to have these work if you were reading them when you'd done pip install ops-scenario but also if you had done pip install ops[testing] and were getting all the classes from the ops.testing namespace. This is also why all the references to the name "scenario" in the docs are gone.
I do have a ticket for updating the charmcraft profiles. I need to get all the bits in places first, but it's definitely in my definition-of-done.
Co-authored-by: PietroPasotti <[email protected]>
|
@PietroPasotti, @benhoyt, or @dimaqq would one of you mind having a quick look over my signature hack to make sure I haven't done anything stupid? No need to re-review all the rest of the changes. You can get the output with |
Hmmm, it's a cool hack, but I don't love it as code in our repo. :-) I wonder if we can hack or monkey-patch Sphinx instead of cluttering the main codebase? |
It does make the signature arguably more correct - I feel like the real hack is the
This should work in theory. I'll work on that. |
…justing the actual classes.
|
@benhoyt what about this version? |
|
Yeah, it's not too bad -- I prefer that over there than polluting the main codebase. (Side note: isn't that going to recurse, calling But let's have a brief discussion during/after daily to finalise this. |
Huh, indeed it ought to. And yet it works somehow. But I'll fix that. |
Had a chat about this - it seems like the two best options (until we can move to Python 3.10) are what's here now or going back to manually crafted Ben's ok with going ahead with this method. |
Expands the docstrings so that when used with Sphinx's autodoc they will fit in with the other ops docs on ops.rtd but also still work standalone. The Sphinx autodoc system uses the `__new__` signature in preference to the `__init__` one, which means that by default all classes that are using the `_MaxPositionalArgs` class have a `*args, **kwargs` signature, which is not informative. custom_conf.py monkeypatches Sphinx to work around this, including tweaking the signature so that the `*` appears in the correct place for the maximum number of positional arguments. Also bumps the Sphinx version to align with ops. --------- Co-authored-by: PietroPasotti <[email protected]>
Expands the docstrings so that when used with Sphinx's autodoc they will fit in with the other ops docs on ops.rtd but also still work standalone.
The Sphinx autodoc system uses the
__new__signature in preference to the__init__one, which means that by default all classes that are using the_MaxPositionalArgsclass have a*args, **kwargssignature, which is not informative. custom_conf.py monkeypatches Sphinx to work around this, including tweaking the signature so that the*appears in the correct place for the maximum number of positional arguments.Also bumps the Sphinx version to align with ops.