DocC documentation generation

[heckj]

Description

Fixes #76

This stubs in a top-level Documentation catalog directory with an initial top-level curation, most of which is surely incorrect or suboptimal, but gets things started. The PR also includes an .spi.yml, which will be picked up SwiftPackageIndex in order to host the documentation at that site (linked from https://swiftpackageindex.com/fireblade-engine/ecs) as updates and releases are made.

Detailed Design

• all standard DocC content locations

Documentation

• establish Documentation catalog directory
• add primary module page
• adds .spi.yml file for hosting
• ported README getting started into an initial article
• started working to add documentation (abstracts for types and methods) to existing types.

Testing

n/a at the moment

Performance

n/a

Source Impact

n/a

Checklist

• I've read the Contribution Guidelines
• I've followed the coding style of the rest of the project.
• I've added tests covering all new code paths my change adds to the project (to the extent possible).
• I've added benchmarks covering new functionality (if appropriate).
• I've verified that my change does not break any existing tests or introduce unexpected benchmark regressions.
• I've updated the documentation (if appropriate).

[ctreffs]

Looks great as initial stub! Thanks for adding this @heckj 🙏
Is there any way to test if SPI integration works? Or do they just parse the repo again with the next release?

Regarding next steps I've updated the feature request with steps that I still see that need to be done. I'd like to hear your thoughts about this. #76 (comment)

[heckj]

The workflow pieces all make a lot of sense - Makefile tweaking should be pretty straightforward. In other projects, I've put this into individual scripts, but the commands are simple enough to really not even need that anymore as DocC has progressed, if you're willing to take on the docc-plugin dependency, which I'd recommend. That's probably what I'll do next, to make it easy to see the content while I'm fiddling with the branch.

The top-level organization (often referred to as "curation" in DocC references), grouping symbols, etc. Needs work and review - there's a lot of types that I grouped just by rough name, but I don't know the details of. I expect as I read more code and get more familiar with specifics, I'll be able to curate it better - as well as propose abstracts and overviews for the types. I set this up without even reaching for what's currently in the wiki pages. The "getting started" content in the README that gets into using the code could easily be an article, and there's broader topics beyond that - families, queries, setting up systems and adding them, that all would benefit from some writing.

[heckj]

Howdy @ctreffs !

This doesn't hit all the points from your issue, but it's growing large as a PR, so I wanted to set it up for proper review and see what you think at this stage. Specifically, it doesn't hit either of:

• Extend documentation content with module pages
• Bonus: Add interactive tutorial

I think what you mean about "extending content with module pages" is setting up curation (organizing methods and overviews) for the key types, and re-organizing things a bit more sensibly. There's enough diversity and complexity in this project that it's going to take me a bit to get fully up to speed with the internals in order to do that, but I can easily continue to extend this PR with that if you'd like.

While I'm confident in what I've created so far, as we get into adding documentation over existing types, I'd like a specific eye from you to verify that I'm not mistaking what methods do, what types are for, etc - which can be a bit more intensive to review.

Alternatively, we can merge this as it is, to get the documentation "as it currently stands" up on Swift Package Index and continue to work on the organization and filling out the types & methods with abstracts (the one-liners that describe what they are/do) with follow-on PRs. Your project, your choice.

[ctreffs]

Great work @heckj, thank you so much. I'd say we keep this as is, it's solid and useful as is and go from there in further PRs.