Include symbol summaries on Home page in CommonMark format

[mattt]

The current version of the Home pages links to each top-level symbol in a bulleted list, with only the symbol's (qualified) name provided. This presentation isn't very information-dense or informative at all.

This PR offers an alternative take that includes quick summaries alongside each symbol. Here's a look of what that looks like for Alamofire:

• Before
• After

This implementation replaces the bulleted list with a definition list. Because those aren't supported in CommonMark (or GitHub Flavored Markdown), it uses raw HTML (<dl> / <dt> / <dd>) tags. However, this isn't a necessary change; if we decide to keep CommonMark output format relatively free of HTML, we could certainly reimplement with a bulleted list instead.

[mattt]

@kaishin Curious to get your take on this proposed design. Any concerns about the markup here? (That is, any strong preference for Markdown unordered lists instead of HTML definition lists?)

[kaishin]

Nice! I think adding the short description is a huge improvement.

To answer your question, I think we need to consider the different use cases. In general, I try to not introduce HTML tags in Markdown to stay as close to the original vision of maximizing readability as possible.

If in this case the Markdown is used purely as an intermediate format for GitHub wikis, then introducing HTML isn't such a big deal. But if users are likely to check the markdown documentation into version control, I think it will hurt plain text readability for those who opt to read the docs in a text editor or a terminal.

I often struggle with this back and forth between the readability of the raw source and the semantic correctness of the output, but if I had to make a snap recommendation in this case, I'd go for dropping them in favor of an unordered list.

[mattt]

Thanks for your feedback, @kaishin! I just pushed a commit to test out what a list would look like with 443096a.

Here's what that looks like in our Alamofire wiki: https://github.com/SwiftDocOrg/Alamofire/wiki/Home/b6a18ab2dc724b6ed6ee0c6150198e6a31490b5b

Although I miss the indented styling GitHub uses for definition lists, I don't think this is significantly worse, at least not enough to wipe out the benefit of using native markup. Any objections to going with this latest format?

[kaishin]

Looks totally acceptable! I imagined a bit worse in my head 😅

[mattt]

Me too! Thanks for the extra set of 👀. Really happy where we ended up with this.