Adding auto generation of table of contents

[paulsmelser]

Instead of needing to redirect the toc to a file manually, this generates a new toc and creates or replaces a contents.md file in the adr folder.

[sephlietz]

This would be the same as adr generate toc > doc/adr/0000-contents.md, right?

[paulsmelser]

@sephlietz More like, adr generate toc | grep -v 0000-contents.md | > doc/adr/0000-contents.md but essentially yes. That's more typing then I want to do though.

We could then do something like: adr new Some New Entry && adr toc instead of adr new Some New Entry && adr generate toc | grep -v 0000-contents.md | > doc/adr/0000-contents.md

[paulsmelser]

I guess it might make more sense to call the other script, grep then redirect to the file. Less repeated code that way.

[sephlietz]

I don't think it makes sense that this adds a superfluous * [Architecture Decision Records](0000-contents.md) into the table of contents when you run adr generate toc. This effectively breaks adr generate toc.

adr toc
cat doc/adr/0000-contents.md
# Architecture Decision Records

* [1. Record architecture decisions](0001-record-architecture-decisions.md)
* [2. Implement as shell scripts](0002-implement-as-shell-scripts.md)
* [3. Single command with subcommands](0003-single-command-with-subcommands.md)
* [4. Markdown format](0004-markdown-format.md)
* [5. Help comments](0005-help-comments.md)
* [6. Packaging and distribution in other version control repositories](0006-packaging-and-distribution-in-other-version-control-repositories.md)
* [7. Invoke adr-config executable to get configuration](0007-invoke-adr-config-executable-to-get-configuration.md)
* [8. Use ISO 8601 Format for Dates](0008-use-iso-8601-format-for-dates.md)

adr generate toc
$ ./src/adr-generate toc
# Architecture Decision Records

* [Architecture Decision Records](0000-contents.md)
* [1. Record architecture decisions](0001-record-architecture-decisions.md)
* [2. Implement as shell scripts](0002-implement-as-shell-scripts.md)
* [3. Single command with subcommands](0003-single-command-with-subcommands.md)
* [4. Markdown format](0004-markdown-format.md)
* [5. Help comments](0005-help-comments.md)
* [6. Packaging and distribution in other version control repositories](0006-packaging-and-distribution-in-other-version-control-repositories.md)
* [7. Invoke adr-config executable to get configuration](0007-invoke-adr-config-executable-to-get-configuration.md)
* [8. Use ISO 8601 Format for Dates](0008-use-iso-8601-format-for-dates.md)

[paulsmelser]

It certainly does. However, I can't think of any reason one would use adr toc then print to the command line using adr generate toc. Frankly, I would just generate the TOC or append to it every time an entry is added or changed.

Anyway, I'm not going to loose any sleep if it's left out but if we're honest there really is no other use for adr generate toc but to redirect it to a file so why not just do it for the user. I suppose we could put it into a sub folder so that the adr generate toc would not pick up the contents.md file but it would be a bit weird to put the toc in a subfolder.

[picaron]

the current toc feature isn't user friendly at all, I'd much rather simply use ad toc and move on with my life ... who needs to print that to the console anyway?

[sephlietz]

I don't really have an opinion, except that it would be confusing to have both adr generate toc and adr toc.

[npryce]

The file naming scheme of "<digits><hyphen><text>.md" is reserved for the ADRs themselves. Anything in the ADR directory that doesn't follow that naming scheme is not treated as an ADR. (E.g. template.md is a template file). So you could call your table of contents file just contents.md and you don't need all the grep -v malarkey.

[npryce]

However (orthogonal to the naming convention comment above) I'd rather that adr-tools did not write derived files into source control. The adr generate ... commands are intended to be used in a document publishing pipeline, that take the source markdown files, generate a table of contents and other derived documents, and convert the whole lot to HTML and/or PDF.

I usually include ADRs in a build for all of a project's documentation, using Make, Pandoc, PlantUML, Mermaid, & Graphviz. (That's one of the reasons ADR tools manipulates plain ol' Markdown files instead of a structured data format).

If you just want to see what ADRs you have, then ls or the directory view in your favourite Git hosting service is intended to be just good enough. (That's why ADR file names start with their index).