doc: update headers and remove manual TOCs #33040

1. 
   l0rinc commented at 11:02 pm on July 22, 2025: contributor

   The table of contents of our markdown documents weren’t always adjusted when corresponding entries were added/removed e.g.

   • Ignoring IDE/editor files: https://github.com/bitcoin/bitcoin/commit/faf65f05312be7647f485f088ba00fef97f47bf4#diff-5e319039d67254bed6ca82562ec5f560f102004aa4806e4ca77f5d0065c65fbbL788-L802
   • Shebang: https://github.com/bitcoin/bitcoin/commit/7777fb8bc749e18c178ef460b65219187e676128#diff-5e319039d67254bed6ca82562ec5f560f102004aa4806e4ca77f5d0065c65fbbL1128-L1144
   • Wallet: https://github.com/bitcoin/bitcoin/commit/fa69c5b170f56d554fcb0d0887bd27f961fe3e74#diff-5e319039d67254bed6ca82562ec5f560f102004aa4806e4ca77f5d0065c65fbbL882-L885
   • Fetch and update PRs individually https://github.com/bitcoin/bitcoin/commit/45b1d39757668939b03b27401c324a938ef0cd8d#diff-fb3fb3681e7dbfc61c47a7d1f890941b8c886cd46fc06cf7839a03a68dc2aa02R188-R200
   • External libmultiprocess installation https://github.com/bitcoin/bitcoin/commit/9ccee9cd022dcce72608831d4b1b93991345b306#diff-41e578ab9c8df11d4143597ad73dbe7be92dba4521a5d17c074b79aad1776ee4R38-R40

   Since GitHub generates these automatically, it suffices if we unify the header styles instead and delete the manual TOC sections.

2. DrahtBot added the label Docs on Jul 22, 2025
3. 
   DrahtBot commented at 11:02 pm on July 22, 2025: contributor

   The following sections might be updated with supplementary metadata relevant to reviewers and maintainers.

   Code Coverage & Benchmarks

   For details see: https://corecheck.dev/bitcoin/bitcoin/pulls/33040.

   Reviews

   See the guideline for information on the review process.

   Type	Reviewers
   ACK	maflcko, janb84, yuvicc

   If your review is incorrectly listed, please react with 👎 to this comment and the bot will ignore it on the next update.

   Conflicts

   Reviewers, this pull request conflicts with the following ones:

   • #30361 (doc: Drop description of LogError messages as fatal by ryanofsky)

   If you consider this pull request important, please also help to review the conflicting pull requests. Ideally, start with the one that should be merged first.

4. 
   yuvicc commented at 4:34 am on July 23, 2025: contributor

   I think we can also add

   0- [Interface Naming Style]([Internal interface
   1    naming style](#internal-interface-naming-style))
   

5. l0rinc renamed this:
   doc: remove dangling toc entries from `developer-notes.md`
   doc: update toc entries in `developer-notes.md`
   on Jul 23, 2025
6. 
   maflcko commented at 6:11 am on July 23, 2025: member

   For reference, GitHub already generates those: https://github.blog/changelog/2021-04-13-table-of-contents-support-in-markdown-files/

   So I guess this is for local usage? Seems fine, but instead of manually updating and reviewing it, it would be better to do with a script. There are many tools (https://github.com/search?q=markdown%20toc&type=repositories) or standalone scripts, such as https://github.com/openai/codex/blob/d6c4083f98094dbd8d86f70992729924d93f73c4/scripts/readme_toc.py#L1.

7. 
   l0rinc commented at 6:15 am on July 23, 2025: contributor

   We can also just delete the whole TOC - but keeping it half-updated seems counter-productive to me
8. in doc/developer-notes.md:1331 in 559ba540e6 outdated

   1327@@ -1322,7 +1328,7 @@ Release notes should be added to a PR-specific release note file at
   1328 All `release-notes*` files are merged into a single `release-notes-<version>.md` file prior to the release.
   1329 
   1330 RPC interface guidelines
   1331---------------------------
   1332+------------------------
   

   ---

   ---

   

   maflcko commented at 6:34 am on July 23, 2025:

   Updating those also seems busy-work and inconsistent with the other headings (#). My preference would be to just use # consistently and not switch between =, -, and # in the same file.

   ---

   

   l0rinc commented at 7:02 am on July 23, 2025:

   Done
9. l0rinc force-pushed on Jul 23, 2025
10. 
    maflcko commented at 7:06 am on July 23, 2025: member

    Seems fine to squash and call it “doc: regenerate toc”?
11. l0rinc force-pushed on Jul 23, 2025
12. l0rinc renamed this:
    doc: update toc entries in `developer-notes.md`
    doc: update headers and TOC in `developer-notes.md`
    on Jul 23, 2025
13. 
    maflcko commented at 10:15 am on July 23, 2025: member

    lgtm ACK f314f01fb833a873c8c75c0d8a21023cf733de9a
14. 
    yuvicc commented at 11:38 am on July 23, 2025: contributor

    ACK f314f01fb833a873c8c75c0d8a21023cf733de9a

    Thanks!

15. 
    janb84 commented at 11:40 am on July 23, 2025: contributor

    lgtm ACK f314f01fb833a873c8c75c0d8a21023cf733de9a
16. 
    achow101 commented at 10:01 pm on July 23, 2025: member

    I would prefer to drop the table of contents entirely.

    I pretty much only ever read .md files on GitHub or with mdcat. On GitHub, the table of contents will be automatically generated, and with mdcat, the links don’t work anyways.

17. 
    l0rinc commented at 10:22 pm on July 23, 2025: contributor

    I’m fine with that option as well, though it’s not the only doc with a TOC:

    • https://github.com/bitcoin/bitcoin/blob/master/doc/productivity.md *
    • https://github.com/bitcoin/bitcoin/blob/master/doc/design/multiprocess.md *
    • https://github.com/bitcoin/bitcoin/blob/master/doc/files.md

    The first two are also missing headers from the TOC - the last one seems up-to-date. So I agree - we either update them all or delete the TOC in all 3 docs.

    Edit: removed the manual TOCs.

18. doc: unify `developer-notes` and `productivity` header styles 26a3730711
19. doc: remove manual TOCs ddab466e0d
20. l0rinc force-pushed on Jul 24, 2025
21. l0rinc renamed this:
    doc: update headers and TOC in `developer-notes.md`
    doc: update headers and remove manual TOCs
    on Jul 24, 2025
22. doc: fix a few obvious typos in the affected files ca38cf701d
23. 
    maflcko commented at 7:03 am on July 24, 2025: member

    lgtm ACK ca38cf701dc635d39db987105c5b2ccc87fd9815 🌔

    Signature:

    0untrusted comment: signature from minisign secret key on empty file; verify via: minisign -Vm "${path_to_any_empty_file}" -P RWTRmVTMeKV5noAMqVlsMugDDCyyTSbA3Re5AkUrhvLVln0tSaFWglOw -x "${path_to_this_whole_four_line_signature_blob}"
    1RUTRmVTMeKV5npGrKx1nqXCw5zeVHdtdYURB/KlyA/LMFgpNCs+SkW9a8N95d+U4AP1RJMi+krxU1A3Yux4bpwZNLvVBKy0wLgM=
    2trusted comment: lgtm ACK ca38cf701dc635d39db987105c5b2ccc87fd9815 🌔
    336ziaowwX9V4b1Jk9vvmqL9RHt/b2G/C/X/i1U/saomVm0xsBNOJcGaEDItgZ5x1G3WzZKoQJyaLO1uVS0cbDw==
    

24. DrahtBot requested review from janb84 on Jul 24, 2025
25. DrahtBot requested review from yuvicc on Jul 24, 2025
26. 
    janb84 commented at 9:26 am on July 24, 2025: contributor

    ACK ca38cf701dc635d39db987105c5b2ccc87fd9815

    changes since last ACK:

    • Removed manual TOCs
27. 
    yuvicc commented at 10:07 am on July 24, 2025: contributor

    re-ACK ca38cf701dc635d39db987105c5b2ccc87fd9815
28. fanquake merged this on Jul 24, 2025
29. fanquake closed this on Jul 24, 2025

    ---

30. l0rinc deleted the branch on Jul 24, 2025

Contributors
l0rinc DrahtBot yuvicc maflcko janb84 achow101

Labels
Docs