Validate examples used in documentation

[fhightower]

To fix #85, we should:

• consolidate examples
• reference examples from .md doc files
• create a test script to validate examples are working properly

[codecov]

Codecov Report

Merging #115 (97a5ae9) into main (d201c35) will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##             main     #115   +/-   ##
=======================================
  Coverage   96.72%   96.72%           
=======================================
  Files           6        6           
  Lines         336      336           
  Branches       39       39           
=======================================
  Hits          325      325           
  Misses          9        9           
  Partials        2        2           

[fhightower]

Something seemed odd with the level of the headings in this document (on this line and this one). I've made a best-guess at what they should be.

[joaufi]

This looks great! :D LGTM. As long as the examples template into the docs correctly (which I'll try to run myself as well shortly) then ✨ 🚀

The example references don't seem to work when mkdocs templated- maybe need a plugin?

[joaufi]

So I was able to run the mkdocs plugin on the feature branch for this PR with:

docker-compose run --rm --service-ports mkdocs

Edit:
The following command also works to access the mkdocs local site from my local:

docker-compose up mkdocs

I accessed it locally at 0.0.0.0:8000; it doesn't look like the way the examples were referenced was templated in correctly:

I wonder if Pydantic uses a plugin to facilitate that linking? I was able to find this Pydantic Issue (it gets a bit salty / heated 😆 ) but unfortunately wasn't able to find any reference to how they accomplish the linking in their docs. 😿

[fhightower]

Thanks, @joaufi ! docker-compose run --rm --service-ports mkdocs works! And thanks for doing some digging into the issue; I'll take a look and get the code snippets rendering properly.

[fhightower]

Ok, I added the necessary, missing extension (markdown-include) and this is working now. @joaufi : Do you mind taking one last look?

[plannigan]

One minor comment