[userdocs] Automatically generate doc indices

[bnbarham]

Add a tool for automatically generating the doc indices for notes,
groups, and features.

[bnbarham]

So I promised I would add verification for this, but after doing that I realized it was only a few lines off of just generating the files instead and thus... here we are 😅

Interested in opinions here as to if:

1. We should add a test case for checking the diff matches after running generate-doc-index.swift
2. This should stay as a script or move into a package
3. If the headers should be pulled from the files themselves (ie. take up to ## Topics) rather than inline in the tool

[DougGregor]

This is very nice, thank you!

[DougGregor]

My thoughts on your questions.

1. I like the idea of adding a test case that checks the diff so we don't forget to update it.
2. Script is fine, no need to introduce a package
3. The headers shouldn't change that often, so I think it's best to leave them in the tool as-is.

[artemcm]

Nice

[DougGregor]

I don't consider the implementation of (1) to be blocking committing this. It's a great step forward, thank you!

[cachemeifyoucan]

LGTM.

I don't know how the swift doc webpage is generated. The alternative to add a test is to make the index generation part of the build steps for the docs.swift.org, but I agree this is not a blocking change.

[bnbarham]

@swift-ci please test

[bnbarham]

Thanks for the input everyone!

I don't consider the implementation of (1) to be blocking committing this. It's a great step forward, thank you!

Easy to add, done.

Script is fine, no need to introduce a package
The headers shouldn't change that often, so I think it's best to leave them in the tool as-is.

Sounds fair to me, thanks 🙇‍♂️

The alternative to add a test is to make the index generation part of the build steps for the docs.swift.org

I did consider that, but it's nice to be able to generate the docs locally when writing them. We could have a docs preview script that generates + starts the docc server though 🤔. For now I've just added the validation in. If it gets too annoying, happy to change.

[bnbarham]

@swift-ci please test macOS platform

[bnbarham]

@swift-ci please test

[bnbarham]

@swift-ci please test

[bnbarham]

@swift-ci please test