Use doctoc to automatically generate TOCs

[lucacome]

Proposed changes

Problem: It's hard to write TOCs and keep them up to date

Solution: Use a doctoc to that automatically

Checklist

Before creating a PR, run through this checklist and mark each as complete.

• I have read the CONTRIBUTING doc
• I have added tests that prove my fix is effective or that my feature works
• I have checked that all unit tests pass after adding my changes
• I have updated necessary documentation
• I have rebased my branch onto main
• I will ensure my PR is targeting the main branch and pulling from my branch from my own fork

Release notes

If this PR introduces a change that affects users and needs to be mentioned in the release notes,
please add a brief note that summarizes the change.

NONE

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 87.62%. Comparing base (f13849a) to head (c9eb47f).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #2213   +/-   ##
=======================================
  Coverage   87.62%   87.62%           
=======================================
  Files          96       96           
  Lines        6715     6715           
  Branches       50       50           
=======================================
  Hits         5884     5884           
  Misses        774      774           
  Partials       57       57           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[mjang]

Question: when I look at Gateway Fabric docs, I already see a doc-level TOC in the left-hand column, and a page-level TOC in the right-hand column.

What's the benefit of this third TOC?

[bjee19]

@mjang , @lucacome could add more details, but I could foresee us using this doctoc tool to help generate developer docs TOCs (the stuff that lives on github only) as there is no standardized way that we are currently doing that.

[salonichf5]

This library is looks great !

[lucacome]

yep this would just be for developer docs, as you can see this PR is mostly replacing existing TOCs there.

[mjang]

@mjang , @lucacome could add more details, but I could foresee us using this doctoc tool to help generate developer docs TOCs (the stuff that lives on github only) as there is no standardized way that we are currently doing that.

Thanks for the explanation! Sounds like a great option to add to whatever template/procedure you have to set up READMEs and similar developer docs.

info: @nginx-jack