Please add config option to disable generating TOC

[joewesch]

When using certain mkdocs themes, the "Topics" (Table of Contents) can be redundant with the same information provided along the side bar.

Topics generated

Topics removed

I'd like to see an option to disable generating this section of the changelog file.

[felixfontein]

I've been thinking about this a bit, including your PR (#191, thanks for that!). I think it definitely makes sense to add more configuration settings like this. Already in this example, there are two levels you can have TOCs in - global and per release; right now the global one is always on, the other always off, with no way to change this. (TOCs on release level are for example enabled in Ansible's changelog, see for example https://github.com/ansible-community/ansible-build-data/blob/main/10/CHANGELOG-v10.md#v10-7-0.)

But I'm not sure whether a global flag "enable/disable top-level TOC" is a good idea. Maybe you want the TOC to be gone for the MD version you want to include in your mkdocs page, but not the MD file you want to have in your repository's root on GitHub (like https://github.com/ansible-collections/community.general/blob/stable-10/CHANGELOG.md, where you can enable an outline, but it's not on by default, at least for me). Or you want the RST version to be different from MD in this regard (RST for a Sphinx page, MD for GitHub).

I think it would be best to have an alternative way to specify output files with (some) individual settings for them, including filename, format, global TOC, and per-release TOC. Something like (with more options for TOC depth):

outputs:
  - file: changelogs/CHANGELOG-v%s.rst
    filename_version_depth: 2
    format: rst
    global_toc: true
    global_toc_depth: 1
    per_release_toc: true
    per_release_toc_depth: 1
  - file: CHANGELOG.md
    format: md
    global_toc: true
    global_toc_depth: 2
    per_release_toc: false
  - file: docsite/CHANGELOG.md
    format: md
    global_toc: false
    per_release_toc: false

This would also make the options changelog_filename_template and changelog_filename_version_depth (both mostly historic and with specific values for backwards compatibility) and output_formats obsolete.

[joewesch]

That makes sense. However, that seems to require a much deeper dive into the code base, and therefore a much longer time commitment, than I can afford to spend on this. If that is the path you want to go, feel free to close my PR and I guess I'll wait for you or someone else to complete the FR.

[felixfontein]

That's very understandable! I'll likely take a look at that on Thursday on my train ride back from CfgMgmtCamp...