update to support descriptions with file links

[logan-markewich]

This PR adds new config options to provide a description with each page link

sections:
  Usage documentation:
    file1.md: Description of file1
    file2.md: Description of file2

Which would generate something like

- [Page Title](page_url): Description of the page

Added some unit tests, so I think this will work nicely? Open to changes!

[adrianlyjak]

you'd need the dashes here still, no? this doesn't look legal on the next line

[logan-markewich]

So from what I understand:

• if you are using descriptions, this format is correct
• the old format (just a list using dashes) also still works

[pawamoy]

But here you're using both formats at once, which is invalid: you'd at least need a trailing colon on the next line.

[logan-markewich]

@pawamoy would be great if we can get this merged. Happy to make any additional changes

[pawamoy]

Thanks a lot @logan-markewich!

What I'd prefer is that we keep using a list, and support items being either a string or a dict (with a single key/value pair):

    sections:
      Usage documentation:
      - file1.md
      - file2.md: Description of file2

This has a few benefits:

• it lets users add descriptions incrementally
• it makes the ordering explicit (in our case dicts would be loaded ordered from Python YAML, but that's not always the case for other languages in which the YAML data could be loaded)

WDYT?

[pawamoy]

But here you're using both formats at once, which is invalid: you'd at least need a trailing colon on the next line.