Convert documentation to using DocC as the primary source of documentation

[Richard-Gist]

Watching the WWDC '21 videos for DocC, I think we should convert all of our documentation over to it. It could replace the jazzy docs we have now, as well as the wiki. It could almost replace our README, but more likely a variant copy of our README would live in the docs. So far I have watched these videos:

• Meet DocC documentation in Xcode
• Elevate your DocC documentation in Xcode
• Host and automate your DocC documentation

There is still one more video coming on how to create interactive tutorials, that I think would also be amazing to add to our documentation, assuming it is indeed as easy as they say.

Some of the biggest benefits I see in switching are:

• XCode warnings when documentation links do not reference to linkable items (a misnamed file or reference)
• Familiar Apple Documentation layout for the generated style.
• The documentation will build for anyone who has consumed our library and is running XCode 13.
• It is hostable on a website for those not running XCode 13.

Biggest drawbacks to consider:

• It's in beta and feels like beta right now. I'm having trouble, reliably creating and regenerating the documentation. This could be user error.
• Would require beta tools in our pipeline to generate the documentation. This means we would need a build-box able to run on Big Sur with XCode 13 Beta.
• The docs cannot be hosted in a github-pages because of the necessary redirects when hosting the docc archive.

It may feel preemptive to do right now, but I'm seeing a lot of value in switching. If we do not switch, we could at least start prepping our existing documentation to minimize the amount of work when XCode 13 is released. This means changing references to class types to using double back-ticks and appropriately using the ## Topics in our .md files.

[Richard-Gist]

A problem we are already thinking about but will absolutely have to address as part of this work is the naming conflict between Workflow the framework and Workflow the class. We can probably work around it, but it is going to cause problems frequently with the auto-complete and reference checking.

[Richard-Gist]

I figured out an easy fix for this. Use

Reference the framework with: ``Workflow``
Reference the class with: ``Workflow/Workflow``

[morganzellers]

I think DocC offers a lot of nice functionality even with the drawbacks. A side benefit of being an early adopter would be to blaze the DocC trail for future Apple projects at WWT as well.

[Richard-Gist]

After having a WWDC Lab on DocC, I've found several answers to these:

Biggest drawbacks to consider:

• It's in beta and feels like beta right now. I'm having trouble, reliably creating and regenerating the documentation. This could be user error.
• Would require beta tools in our pipeline to generate the documentation. This means we would need a build-box able to run on Big Sur with XCode 13 Beta.
• The docs cannot be hosted in a github-pages because of the necessary redirects when hosting the docc archive.

The beta aspects were entirely user error. I needed to update the swift tools version for the package and select the appropriate scheme. Both of these would be resolved in a pipeline that generates the documentation.

Requiring beta tools to generate is unfortunate but completely fixable by switching some of our pipeline if not all of it to MacStadium. We would have a dedicated box that we would setup as a runner that would be responsible for documentation and beta builds.

As for hosing on github-pages, I am currently looking into an unsupported workaround, but so far it sounds promising and I think it will work. If we are successful, this will provide the best experience in my opinion.

[Tyler-Keith-Thompson]

Copying my comment from the issue, since this is where the discussion is really happening:
I appreciate the line of thinking here. I tend to agree, yeah it's in beta, yeah it may be a little flakey....we should use it. The tutorials, and the web hosting, and the general awesomeness of letting people open the archive is simply too much to pass up on. Plus we'll look pretty hip if we're one of the first to adopt the new DocC stuff.

[morganzellers]

Decision resulted in the creation of Issue #49 to be worked when we have capacity.