nimi-python
nimi-python copied to clipboard
Published
20 hours ago •
ni
ni
Repeated Capabilites documentation improvements
- [X] This contribution adheres to CONTRIBUTING.md.
- [ ] ~I've updated CHANGELOG.md if applicable.~
- [X] I've added tests applicable for this pull request
What does this Pull Request accomplish?
There are several issues open against the way we document usage of repeated capabilities in our rep_caps.rst pages.
Summary of Issues
- We present implementation details that the user doesn't care about
- These may be useful to contributors, but to everyone else they're just distracting.
- We list all of the possible types that can be passed to the indexing operator but don't make it clear what the recommended or "pythonic" types are.
- This information is worth keeping, but we need to provide better guidance.
- We use channel_enabled in all of our examples, though it may not actually support the repeated capability in the example code and not all apis have a channel_enabled property.
This PR addresses these by doing the following:
- Explicitly recommend what types to pass to the indexing operator.
- Present examples which demonstrate accessing the repeated capability with some of our recommended types.
- Do not present examples using other types.
- Specify fields in metadata used to build real examples specific to each rep cap
- New helper functions were added to return the snippet and explanation for each example
List issues fixed by this Pull Request below, if any.
- Fix #1388
- Fix #1334
- Fix #1126
What testing has been done?
Local code generation with documentation inspection.
I haven't committed the results of tox -e codegen.
I can do that when there's agreement on the contents of rep_caps.rst.mako.
I haven't committed the results of tox -e codegen. I can do that when there's agreement on the contents of rep_caps.rst.mako.
No, please commit them before the PR is ready for review so we can see the effects and merge without having to track anything.
