Skip to main content

Generate a table of contents from the comments of a file

Project description

toc

Generate a table of contents from the comments of a file

Example table of contents generated by toc

What is it?

toc is a CLI utility to generates Table of Contents of text files. It aims to be the tree for the contents of a file, instead of a directory.

toc comes with native support for Markdown, AsciiDoc, reStructuredText, HTML and many more. It can support any language through a special kind of comments.[^1]

Why should I use it?

Few reasons that you may consider:

  • it can make your files and code base understandable in seconds, to you and others
  • you can jump directly to the section you need to edit, because you see where it's located
  • it makes you reflect about the structure of your file

How does it work?

For markup languages such as Markdown, AsciiDoc, reStructuredText and HTML, no changes are needed. For other languages (e.g. C), write some comments representing the different sections of a file.[^1] After this, run toc on that file to turn those comments into a table of contents.

Comments are structured in this way:

Syntax of comments used to generate table of contents

By running toc file.c, you will read the table of contents of that file:

Toc generated from syntax comments

How can I install it?

First, you need Python installed in your system.

Then, you can install toc by running:

pip install tableofcontents

If you are using Arch or Manjaro Linux, you can install toc directly from the AUR.

You should now be able to run toc -h to display a list of parameter you can use.

See USAGE.md for step-by-step explanations of different features, and a list of languages supported natively or that need special attention (e.g. CSS)

How can I contribute?

See CONTRIBUTING.md

What has changed from previous versions?

See CHANGELOG.md

[^1]: For examples of valid and invalid comments, see https://regex101.com/r/ngzZXN/2

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

tableofcontents-2.7.3.tar.gz (28.2 kB view details)

Uploaded Source

Built Distribution

tableofcontents-2.7.3-py3-none-any.whl (25.5 kB view details)

Uploaded Python 3

File details

Details for the file tableofcontents-2.7.3.tar.gz.

File metadata

  • Download URL: tableofcontents-2.7.3.tar.gz
  • Upload date:
  • Size: 28.2 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/5.0.0 CPython/3.12.7

File hashes

Hashes for tableofcontents-2.7.3.tar.gz
Algorithm Hash digest
SHA256 392bc939b8c0fa66115d0d84caec525d7172047804a0da0c7a52bc5a05ddd193
MD5 9dc88393abca448e944ea53bf5860031
BLAKE2b-256 cc8c60eb6d6c59639e570a43e23397bf4d7cff688f45ba6e8107188299980bca

See more details on using hashes here.

File details

Details for the file tableofcontents-2.7.3-py3-none-any.whl.

File metadata

File hashes

Hashes for tableofcontents-2.7.3-py3-none-any.whl
Algorithm Hash digest
SHA256 e832d233d0312f02db16a366380c964b9cf47ebc5c1bc3279ca15ec45e5199ca
MD5 d537ec5843ff45a75486abcdaab4cc96
BLAKE2b-256 efb18037e37fd0a121f2c93e41bb50cd9bf638ce8e728fbcf41742aef9d0c59c

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page