Generate tables of contents for code files (various languages).
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
LICENSE
Makefile
README.md
sourcetoc.ml

README.md

sourcetoc computes a table of contents for a source code file based on headings found in comments.

/* <TOC> */                      >>>>      /* <TOC> */
/* </TOC> */                               /* Section 1 ...................  8
                                            *   Section 1.1 ...............  9
// == Section 1 ==                          * Section 2 ................... 13
// === Section 1.1 ===                      */
                                           /* </TOC> */
...
                                           // == Section 1 ==
// == Section 2 ==                         // === Section 1.1 ===

...                                        ...

                                           // == Section 2 ==

                                           ...

sourcetoc supports three styles of headings (wiki, atx (markdown) and html) and a number of programming languages (no strong integration).

Install

Requirements: OCaml ≥ 3.12

To install once do sudo make install.

To get sourcetoc with updates you can do:

git clone https://github.com/nahoj/sourcetoc.git
cd sourcetoc
sudo make lninstall  # creates a symlink

And then to update:

cd sourcetoc
git pull

Usage

Basic usage:

sourcetoc example.py

This will modify example.py in place after copying it to example.py~.

In a file, sourcetoc considers one-line comments that start at the beginning of a line and contain either <TOC> or </TOC> or a heading. sourcetoc works line by line and does not ignore comment lines that might have a different meaning because of context (e.g. inside a multi-line string).

/* == Valid == */

/* == Invalid (multi-line) ==
 */

 // == Invalid (space) ==

String s = "
// == Valid (context ignored) ==
";

The table of contents is generated from the list of headings and is inserted between the <TOC> and </TOC> lines. These two must be unique and appear in this order. Anything that exists between them (typically a previous version of the TOC) is erased. The rest of the file is unchanged.

By default sourcetoc expects wiki-style headings (== ... ==). It also supports atx/Markdown headings (## ... ##) and HTML headings (<h2>...</h2>). Use --heading-style.

See sourcetoc --help for the full list of options.