Basic mkdocs documentation setup

[rlskoeser]

this pr adds basic documentation setup

• docs dependencies added as extra / optional install in setup.py
• very basic mkdocs setup; pulled in the existing docs/*.md files, linked the main readme to be the index of the docs site, added a code reference file to generate docs from code docstrings using google format
• added notes to contributing file about docstring format and instructions for building docs locally
• github action to publish mkdocs —based on https://github.com/marketplace/actions/deploy-mkdocs ; not sure how to test this before merging! at minimum a maintainer will need to configure a GITHUB_TOKEN secret to allow the deploy

should be possible to create PR check to confirm documentation builds correctly, and maybe even check documentation coverage, but I'm less familiar with mkdocs than sphinx

[azaroth42]

Looks great, agree not sure how to test other than to merge and see what happens.

[rlskoeser]

ok, I've updated the workflow so it will build docs in strict mode on pull requests (which required me to do a little docstring cleanup — if you look at previous builds you can see it failed), and then should build & publish on push to main.

[digitaldogsbody]

Great work - thanks!

[glenrobson]

I'm afraid the build failed on master: https://github.com/iiif-prezi/iiif-prezi3/runs/6633389984?check_suite_focus=true

[digitaldogsbody]

mkdocstrings/mkdocstrings#215

[rlskoeser]

@glenrobson sorry I haven't gotten back to this, was thinking to open a pr with a suggested fix but haven't had time. It seems like the mkdocs workflow action doesn't use the same environment as the workflow where we're installing dependencies. I think the simplest thing would be to build the docs similar to the way we build them on PRs (or maybe that exact same action), and then use a different GH action to publish.

[digitaldogsbody]

• github action to publish mkdocs —based on https://github.com/marketplace/actions/deploy-mkdocs ; not sure how to test this before merging! at minimum a maintainer will need to configure a GITHUB_TOKEN secret to allow the deploy

I think the GITHUB_TOKEN will be created and exposed automatically when the fixed workflow runs (after merge), but we will have to configure the Github Pages setup after the first run only (per the last paragraph of https://github.com/marketplace/actions/deploy-mkdocs#building-with-github_token)