ShinyCMS

Today I merged PR #661 - Did Somebody Say Documentation?

The highlights of this PR are:

• Each major feature and each plugin now has its own Markdown documentation file in the /docs folder
• The new ShinyCMS documentation website is generated from the files in /docs, using MkDocs

The docs website is hosted on GitHub Pages, which is pretty straightforward to set up and keep updated with MkDocs. When I run 'mkdocs build' MkDocs generates a HTML version of each of my Markdown docs (applying my chosen theme at the same time), and puts them all in the /site directory. When I run 'mkdocs gh-deploy' it pushes the contents of that directory to the special gh-pages branch that GitHub Pages serves the site from.

The only fiddly bit was preventing CircleCI from trying to run my tests on that gh-pages branch, as they would fail spectacularly on account of it having no actual code in it. The solution I went for in the end was to put a minimal 'do nothing' CircleCI config in /site; MkDocs kindly leaves this in place when I run 'mkdocs build', and then pushes it up along with the rest when I run 'mkdocs gh-deploy'.

Currently, most of the documentation for the features and plugins ranges from 'not very detailed' to 'this stub file is basically empty' - but all of the documentation is a lot more likely to get fleshed out (or started!) now that the files are all there, ready and waiting.

Tags: documentation docs markdown website mkdocs github github pages tests ci circleci