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!

[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?

[logan-markewich]

Thats fair @pawamoy -- I can make that change

[logan-markewich]

@pawamoy ok, I think this is kind of what you were getting at? While the tests pass, I don't actually know how to give this an mkdocs.yml to test e2e 😅 But if you want to take it for a spin go for it!

[pawamoy]

I tried to simplify the code: we now always expand the inputs into a dict of sections (key = section name) where values are dicts of files (key = relative file path, value = description). This way it's expanded once and for all and we avoid intermediate transformations or additional variable to store intermediate data.

You could think: "why not reading dicts directly from the config file then" (since I made you go from dicts to lists), and the answer would be: the YAML syntax wouldn't allow you to have keys without values, so the list makes it a bit more elegant IMO.

sections:
  Some section:
    page1.md:  # not elegant
    page2.md: description

sections:
  Some section:
  - page1.md  # colon not needed, more elegant
  - page2.md: description

(also we maintain backward compatibility)

I also reworked the tests. Let me know what you think 🙂