Rewrite the documentation

[Pennycook]

Related issues

Closes #19.

Proposed changes

• Remove the old configuration documentation and examples.
• Add Sphinx documentation, including a worked tutorial and command-line option reference.
• Update the README to include badges and links to other parts of the documentation.
• Add the Code of Conduct, which was missing.

Note that the README changes remove the IMPORTANT callout about the change in codebasin behavior. The plan is that we'll include this in the Release Notes instead, so that we can have a clean break for the new documentation.

[Pennycook]

The changes in 5fdc696 partially address #45. The help strings now have the same form, but the formatting is less than ideal due to the way that certain option descriptions wrap. We should keep #45 open until that's fixed.

[laserkelvin]

A few minor checks.

Also, I know we don't need it as a dependency persay, but do you need to document the version of sphinx and extensions for building the docs somewhere?

[laserkelvin]

Does it directly? Or is it just by going through the gambit of finding residuals after running every possible target?

[Pennycook]

The latter, I think. Code in a file that isn't touched by any platform in the configuration file gets associated with the empty platform set, and also called out as a percentage of SLOC:

---------------------------------------------
                      Platform Set LOC % LOC
---------------------------------------------
                                {}   2  4.88
                           {GPU 1}   1  2.44
                           {GPU 2}   1  2.44
                           {CPU 2}   1  2.44
                           {CPU 1}   1  2.44
                            {FPGA}  14 34.15
                    {GPU 2, GPU 1}   6 14.63
                    {CPU 1, CPU 2}   6 14.63
{FPGA, CPU 1, GPU 2, GPU 1, CPU 2}   9 21.95
---------------------------------------------
Code Divergence: 0.55
Unused Code (%): 4.88
Total SLOC: 41

We can't identify code we don't see at all.

[laserkelvin]

Maybe worth considering this as a feature in the future and have some routines that sniff the files to see if they could be code or not, and have a "lines of potentially stale code" value as well since unused code is still a maintenance burden.

[Pennycook]

Great idea. I've opened #86 to track this.

The legacy interface (arguably) had better support for this, because the user was required to describe all the code in the codebase (via globs) in addition to providing the compile commands. But it still wasn't perfect, because we couldn't identify source files outside of the globs. Actually walking the source directory and alerting the user to anything we find would be much more useful.

[Pennycook]

Also, I know we don't need it as a dependency persay, but do you need to document the version of sphinx and extensions for building the docs somewhere?

I've added a README explaining that sphinx and furo are required in ae283fe.