Allow for inline, manual documentation of Endpoints in definition.

[pobocks]

Description

These changes make it possible to add a documentation block (in markdown) and an example in any language supported by Rouge to an Endpoint.

Motivation and Context

The auto-generated API docs are a useful resource, but are in many cases unhelpful, misleading, or downright inaccurate. Shell examples are wrong more often than right for endpoints that aren't resources or simple collections of same-type resources. At the same time, they're the best we have, and replacing them with something better will take time and effort.

This code allows for manual docs to be inserted, while falling back to the existing generated docs.

How Has This Been Tested?

I added calls to Endpoint#documentation and Endpoint#example in the spec for the REST helper.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)

Checklist:

• My code follows the code style of this project.
• My change requires a change to the documentation.
• I have updated the documentation accordingly.
• I have read the CONTRIBUTING document.
• I have added tests to cover my changes.
• All new and existing tests passed.

[p-galligan]

I'm in support of this change, and it looks good to me!

[lmcglohon]

@pobocks I figured out how to add information using the documentation piece but I am not sure how to add information using the example piece. Can you please add more information on how to use the example piece?

@pobocks Nevermind - I got it to work

[lorawoodford]

@pobocks going to let the tests pass, then will merge.

@lmcglohon @cdibella and I discussed the possibility of having the Python tab (well, once someone adds the first Python example and there is a Python tab) default to a "no example has been provided for this endpoint yet, please consider providing one" sort of blurb, but that can be a future enhancement.

Thanks for this.

[pobocks]

Very welcome!

Re: the Python tab thing, if that's something that's desirable, I'm happy add it in, I'm gonna be in there documenting at least a few endpoints so there are examples, anyway.

Also, I wanna re-up the question of whether we should come up with a criteria for Python examples, like, I think the following questions ought to be answered maybe?

A) Should it assume dependencies are available, or use stdlib only?
B) requests or asnake?

I think in either case, I'd want to add an explainer to the docs re: what we're doing (and maybe some boilerplate that we don't want to repeat per-example, i.e. where to get whichever library and how to import it and authenticate, in the authentication section.