Injecting examples into docs at build-time #402
Conversation
mtdowling
added
the
pr/needs-review
|
Could I get a screenshot of what this looks like? |
|
|
| @@ -22,9 +24,12 @@ | |||
|
|
|||
|
|
|||
| class ServiceDocumenter(object): | |||
| def __init__(self, service_name, session): | |||
| def __init__(self, service_name, session, examples_file=None): | |||
There was a problem hiding this comment.
Another idea is that we can make the examples directory a EXAMPLES_DIRECTORY in the class that you can override when you instantiate the class and move the _get_examples_file() to when the document_service() call is made. As this argument seems to only be needed for testing.
There was a problem hiding this comment.
I'll update to use that approach thanks
|
Looks good. Had some small comments. Another comment that I have is make sure you update the It would be sort of simiiar to what we do for the CLI: |
mtdowling
added
incorporating-feedback
and removed
pr/needs-review
|
Feedback incorporated. I just need to add a local TOC to the examples file. |
| def _get_example_file(self): | ||
| return os.path.realpath( | ||
| os.sep.join([self.EXAMPLE_PATH, | ||
| self._service_name + '.rst'])) |
There was a problem hiding this comment.
FWIW, I would prefer to use os.path.join(..., ..., ...) in favor of os.sep.join([..., ..., ...]), because it is conceptually a high level API.
This is NOT a must-fix. I will still give out a "ship-it" for this PR based on its current implementation.
There was a problem hiding this comment.
Ah, yes. That's much nicer. Thanks!
|
I've added a built-in local table of contents to the injected examples section. This relies on placing example titles as
|
mtdowling
added
pr/needs-review
|
🚢 |
|
LGTM 🚢 |
Injecting examples into docs at build-time
|
⛵ |
This PR adds the ability to inject examples into service documentation at doc build-time. Each service can have a file stored under
boto3/examples/<service-name>.rst. If found, the contents of this file will be injected into each service's documentation output at the bottom in an "Examples" section.@kyleknap