Fix up CI doco toolchain - migrate to VuePress

[SubPointSupport]

Currently, SPMeta2 uses a custom tailored, Wyam based workflow to generate documentation across several projects. This approach proven to be ineffective, complex and slow.

This is very similar to blog platform problem - instead of reinventing the wheel, an appropriate solution such as Medium better be used.

Here is the current state:

• custom crafted Wyam workflow wastes our resources
• current Wyam is outdated, too much effort to upgrade
• feature-wise, not much offered out of the box
• slow feedback loop on Wyam based editing
• complex, resourceful Wyam theme customization workflow
• design, styling and other non-tech things require custom work
• CI integration is bulky, complex and fragile
• It's all just so wrong!

Pretty much, we should be focusing on projects rather than on crafting custom engines for project documentation. All non-tech work, such as blog, doco and so on should be outsourced to the right platform or tool.

As a solution, the following changes are proposed:

• ~~~Get rid of custom tailored Wyam workflow~~~
• Stick to a mainstream solution (middleman, jekyll, hexo, vuepress, etc.)
• Containerize doco build, use Docker container, don't limit ourselves to windows platform
• Use AppVeyor for CI builds; compilation, tests and NuGet packaging
• Use AppVeyor CI for doco builds; linux based Docker builds
• Continue using Netlify for doco publishing

Using an off the shelve solution for documentation is the right way in out situation. As for the projects, a few stages are proposed:

• try out on metabox / metapack doco
• ~~~bring Roslyn based code analysis under Docker container for SPMeta2/reSP -> generate C# samples~~~
• use generated C# sample index with the next Docker container within middleman, jekyll, hexo, vuepress or other static site generator

This work should take priority so that we would be able to maintain a consistent, easy-to-edit and up to date doco.

[SubPointSupport]

After some research, the following learnings and path forward are suggested. In a nutshell, we are ditching any custom or heavily customized solutions for web sites and documentation.

• Middleman is the primary choose at the moment.
• VuePress is the primary choice for doco
• All heavily driven via CI workflow: edit -> git commit -> publish continuously via CI
• No heavy customization to avoid time/resource waste

Current progress expands original ticket description. Main change is ditching Roslyn, removing all custom code, and moving all source code examples back into markdown files. ETA is around 2 weeks, mid-June, to move current POCs into public github projects, setup CI and migrate content. Partly, most of the tasks (apart content migration) were already implemented in NET/C#/AppVeyor and need only re-implementation under new environment - Docker/Travis CI. Content migration is the heaviest, manual process.

Current progress

• use Middleman for static web site
• use VuePress for all documentation
• use markdown as a single point of truth for all data (text and source code examples)
• remove dynamic sample generation off the source code via Roslyn (too complex), move all code samples into markdown
• implement POC on spmeta2, reSharper, metabox and metapack doco
• use only one customization - mermaid library for diagrams
• implement Docker containers for Middleman
• implement Docker containers for VuePress
• use a light Vagrant box ailispaw/barge with Docker pre-installed (to support both Windows/MacBook dev experience)
• publish POC project with Vagrant/Docker setup for Middleman/VuePress
• integrate AppVeyor CI build
• integrate Netlify build
• migrate outstanding doco, enable VuePress github edit links

[SubPointSupport]

Current progress on 11/06/2018

POC is completed under dev-1116 branch in doco repo:

https://github.com/SubPointSolutions/subpointsolutions-docs/tree/dev-1116

Works on both windows/mac platforms, uses AppVeyor CI for continuous publishing . Ruby scripts heavy lift build orchestration, Vagrant/Docker and AppVeyor ensures portability and CI:

• get all project repos based on YAML spec
• orchestrate vuepress build locally or under docker container, build documntation
• publish doco to corresponding netlify web site locally or under docker container
• all this works locally on windows (locally or vagrant -> docker) and on macos (locally or docker), and then we use AppVeyor CI to push changes automatically

vuepress provides rich features around navigation, edit on github links, search and many others. So far, we use zero customization. Currently, the content looks ugly - not all content was portend, not much navigation was setup, and then code samples have to be moved as well (further content migration work)

https://subpoint-docs-vuepress-dev.netlify.com/metabox
https://subpoint-docs-vuepress-dev.netlify.com/spmeta2
https://subpoint-docs-vuepress-dev.netlify.com/resp

AppVeyor buillds:

https://ci.appveyor.com/project/SubPointSupport/spmeta2-docs

Outstanding work is more of a routine doco migration and content writing:
Previous scope

• implement mermaid library for diagrams
• migrate outstanding doco (described in more details below)

Pre-Content migration scope

• implement landing page (index page) for doco web site
• remove navigation menu from landing page layout
• implement branch builds (dev/beta/master) - small changes on AppVeyor side

[SubPointSupport]

• implement mermaid library for diagrams, dev branch in work can be seen below:

demo: https://subpoint-docs-vuepress-dev.netlify.com/spmeta2/getting-started/
src: https://github.com/SubPointSolutions/subpointsolutions-docs/tree/dev-1116

[SubPointSupport]

• implement branch builds (dev/beta/master) - small changes on AppVeyor side

dev-1116 branch -> dev site -> https://subpoint-docs-vuepress-dev.netlify.com/
dev-1116-beta branch -> beta site -> https://subpoint-docs-vuepress-beta.netlify.com/

build.yaml drives repository setup. Publishing trigger might be either dev -> beta branch move on the source repository or manual trigger on beta/master branch of docs repository, that's in discussion.

This ends technical milestone leaving open only non-technical content migration across 6 repos + newly added metabox (7 in total).

Content migration scope

• migrate documentation across 7 repositories - lift and shift content, navigation and code samples from the current repos and http://docs.subpointsolutions.com
• write documentation / contribution workflow for doc build itself
• switch current doco site to "old" site
• set vuepress bases doco site as "new site", add link to "old site"