Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/AlphaJack/toc
Generate a table of contents from the comments of a file
https://github.com/AlphaJack/toc
comment-system comments python regex tableofcontents toc-generator
Last synced: about 1 month ago
JSON representation
Generate a table of contents from the comments of a file
- Host: GitHub
- URL: https://github.com/AlphaJack/toc
- Owner: AlphaJack
- License: gpl-3.0
- Created: 2023-11-03T11:22:36.000Z (8 months ago)
- Default Branch: master
- Last Pushed: 2024-03-21T22:13:07.000Z (3 months ago)
- Last Synced: 2024-04-22T03:12:49.201Z (about 2 months ago)
- Topics: comment-system, comments, python, regex, tableofcontents, toc-generator
- Language: Python
- Homepage:
- Size: 818 KB
- Stars: 13
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Lists
- cli-apps - toc - Generate a table of contents from the comments of a file. (<a name="text-processing"></a>Text processing)
- awesome-cli-apps - toc - Generate a table of contents from the comments of a file. (<a name="text-processing"></a>Text processing)
README
# toc
Generate a table of contents from the comments of a file
## What is it?
`toc` is a command line utility that generates the table of contents of a file from a special kind of comments.
Think it as a [`tree`](https://en.wikipedia.org/wiki/Tree_%28command%29) for the contents of a file, instead of a directory.
## Why should I use it?
Few reasons that you may consider:
- it can make your files understandable in seconds, even if you haven't touched them for a while
- you can jump directly to the section you need to edit, because you know where it's located
- it makes you reflect about the structure of your file, making it more logical
- for software developers, it makes your code base more readable to others
## How does it work?
First, you have to write the comments representing the different sections of a file.
Second, you run `toc` on that file to turn those comments into a table of contents.
Comments are structured in this way:
```c
┌ comment character ("#", "//", "%", ";", "--", etc., according to the file language)
│
│ nesting level ("#" repeated 64, 32, 16, 8, 4 or 2 times) section name
│ ┌──────────────────────────────┴───────────────────────────────┐ ┌────┴────┐
// ################################################################ First level
// ################################ Second level
// ################ Third level
// ######## Fourth level
// #### Fifth level
// ## Sixth level
```
By running `toc file.c`, you will read the table of contents of that file
```c
// ┌───────────────────────────────────────────────────────────────┐
// │ Contents of file.c │
// ├───────────────────────────────────────────────────────────────┘
// │
// ├──┐First level
// │ └──┐Second level
// │ └──┐Third level
// │ └──┐Fourth level
// │ └──┐Fifth level
// │ └── Sixth level
// │
// └───────────────────────────────────────────────────────────────
```
This table of contents of that file can also be embedded in the original file with `toc -f file.c`
## How can I use it?
First, you need [Python](https://www.python.org/downloads/) installed in your system.
Then, you can install toc by running:
```bash
pip install tableofcontents
```
If you are using Arch or Manjaro Linux, you can install [toc](https://aur.archlinux.org/packages/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](./USAGE.md) for step-by-step explanations of the different features, and languages that don't need comments (e.g. Markdown) or needs special attention (e.g. CSS)
See for examples of valid and invalid comments.
## How can I contribute?
See [CONTRIBUTING.md](./CONTRIBUTING.md)
## What has changed from previous versions?
See [CHANGELOG.md](./CHANGELOG.md)