### Set Up a Virtual Environment and Install Project

Source: https://github.com/alphajack/toc/blob/master/CONTRIBUTING.md

Create a virtual environment, activate it, and install the project in editable mode.

```bash
python -m venv "venv/"
source venv/bin/activate
pip install -e .
```

--------------------------------

### Install toc CLI

Source: https://github.com/alphajack/toc/blob/master/README.md

Install the 'toc' package using pip. Ensure Python is installed on your system first.

```bash
pip install tableofcontents
```

--------------------------------

### Install and Run MyPy for Type Checking

Source: https://github.com/alphajack/toc/blob/master/CONTRIBUTING.md

Install the mypy package and run it to check type consistency in the 'toc/' directory.

```bash
pip install mypy
mypy "toc/"
```

--------------------------------

### Get Usage Information

Source: https://github.com/alphajack/toc/blob/master/USAGE.md

Run 'toc -h' to display the help message and view all available commands and options for the 'toc' CLI.

```bash
toc -h
```

--------------------------------

### Run Unit Tests and Generate HTML Coverage Report

Source: https://github.com/alphajack/toc/blob/master/CONTRIBUTING.md

Install coverage, run unit tests, generate an HTML report, and open it in a browser.

```bash
pip install coverage
coverage run -m unittest
coverage html
firefox "htmlcov/index.html"
```

--------------------------------

### Install and Run Black for Code Linting

Source: https://github.com/alphajack/toc/blob/master/CONTRIBUTING.md

Install the black package and run it to format code according to PEP 8 style guidelines.

```bash
pip install black
black .
```

--------------------------------

### Example File List for `toc -l`

Source: https://github.com/alphajack/toc/blob/master/USAGE.md

This is an example of a `files.txt` content used with `toc -l`. It includes regular files, comments, and glob patterns.

```text
# ignore-this-file.txt
README.md
USAGE.md
CHANGELOG.md
toc/cli.py
toc/toc.py
# glob expansion
tests/test*.py
```

--------------------------------

### Get Version Information

Source: https://github.com/alphajack/toc/blob/master/USAGE.md

Run 'toc -v' to display the current version of the 'toc' tool.

```bash
toc -v
```

--------------------------------

### Line-Level Profiling with pprofile and qcachegrind

Source: https://github.com/alphajack/toc/blob/master/CONTRIBUTING.md

Utilize pprofile for line-level time profiling. Install pprofile and use qcachegrind for visualization. The --exclude-syspath flag can be useful.

```bash
pip install pprofile
pprofile --exclude-syspath -f callgrind -o "tests/output/prof_callgrind.prof" toc/cli.py "tests/output/longfile.txt"
qcachegrind "tests/output/prof_callgrind.prof"
```

--------------------------------

### Launch TOC Without Installation

Source: https://github.com/alphajack/toc/blob/master/CONTRIBUTING.md

Run the TOC CLI directly using the python -m command for testing or development without a formal installation. This is useful for quick checks.

```bash
python -m toc.cli --version
python -m toc.cli -f "toc/toc.py"
```

--------------------------------

### TOC Output from Stdin

Source: https://github.com/alphajack/toc/blob/master/USAGE.md

This HTML-formatted output is an example of what 'toc' might generate when processing input from stdin, with the file extension set to 'html'.

```html
<!--
// ┌───────────────────────────────────────────────────────────────┐
// │ Contents of stdin.html                                        │
// ├───────────────────────────────────────────────────────────────┘
// │
// ├──┐Search code, repositories, users, issues, pull requests...
// │  └──┐Use saved searches to filter your results more quickly
// │     └── License
// ├──┐AlphaJack/toc
// │  ├──┐About
// │  │  ├── Topics
// │  │  ├── Resources
// │  │  ├── License
// │  │  ├── Stars
// │  │  ├── Watchers
// │  │  └── Forks
// │  ├── Languages
// │  └──┐Footer
// │     └── Footer navigation
// │
// └───────────────────────────────────────────────────────────────
-->
```

--------------------------------

### Function-Level Profiling with cProfile and snakeviz

Source: https://github.com/alphajack/toc/blob/master/CONTRIBUTING.md

Use cProfile for function-level time profiling. Install snakeviz for visualization. This command profiles the CLI script and saves output to a file.

```bash
pip install snakeviz
python -m cProfile -o "tests/output/prof_cprofile.prof" toc/cli.py "tests/output/longfile.txt"
snakeviz "tests/output/prof_cprofile.prof"
```

--------------------------------

### Process Multiple Files Using a Glob List

Source: https://github.com/alphajack/toc/blob/master/USAGE.md

Use `toc -l -f files.txt` to process multiple files listed in `files.txt`. Lines starting with '#' are ignored, and glob expansion is supported.

```bash
toc -l -f files.txt
```

--------------------------------

### Initial `example.js` Content with TOC

Source: https://github.com/alphajack/toc/blob/master/USAGE.md

This is the content of `example.js` after the initial TOC generation, showing the structure recognized by the `toc` tool.

```javascript
#!/usr/bin/env node

// 
// Contents of example.js                                        
// 
// 
// 	Main section
// 		Nested section
// 			Nested section
// 				Nested section
// 					 Nested section
// 
// 

// ################################################################ Main section

let Section1 = "Write //, 64 hash characters and the name of section"

// ################################ Nested section

let Section2 = "Write //, 32 hash characters and the name of section"

// ################ Nested section

let Section3 = "Write //, 16 hash characters and the name of section"

// ######## Nested section

let Section4 = "Write //, 8 hash characters and the name of section"

// #### Nested section

let Section5 = "Write //, 4 hash characters and the name of section"

```

--------------------------------

### Release Steps: Tagging and Changelog

Source: https://github.com/alphajack/toc/blob/master/CONTRIBUTING.md

Create a temporary tag, update the changelog using git-cliff, and add the changelog changes to git.

```bash
git tag v2.6.0
git add CHANGELOG.md && git commit -m "minor: updated CHANGELOG.md"
```

--------------------------------

### Generate Multiple Small Files for Benchmarking

Source: https://github.com/alphajack/toc/blob/master/CONTRIBUTING.md

Creates multiple small text files with simple markdown headers and a list file pointing to them.

```bash
mkdir -p tests/output/multi
rm -f tests/output/multi/_list.txt
for i in {1..10000}; do
 file=tests/output/multi/$i.txt
 {
  printf "# ################################################################ Test H1 $i\n"
  printf "# ################################ Test H2 $i\n"
 } > $file
 printf "$file\n" >> tests/output/multi/_list.txt
done
```

--------------------------------

### Release Steps: Push Tags and Upload

Source: https://github.com/alphajack/toc/blob/master/CONTRIBUTING.md

After updating the version and changelog, push all new commits and tags to the remote repository. This includes uploading to PyPI.

```bash
git push --follow-tags
```

--------------------------------

### Release Steps: Update Changelog

Source: https://github.com/alphajack/toc/blob/master/CONTRIBUTING.md

Generate and update the CHANGELOG.md file using git-cliff with the specified configuration.

```bash
git-cliff -c pyproject.toml > CHANGELOG.md
```

--------------------------------

### Generate Multiple Complex Files for Benchmarking

Source: https://github.com/alphajack/toc/blob/master/CONTRIBUTING.md

Creates multiple small text files with complex markdown headers and a list file pointing to them.

```bash
mkdir -p tests/output/multi
rm -f tests/output/multi/_list-complex.txt
for i in {1..10000}; do
 file=tests/output/multi/$i-complex.txt
 {
  printf "# ################################################################ Test H1 $i\n"
  printf "# ################################ Test H2 $i\n"
  printf "# ################ Test H3 $i\n"
  printf "# ################ Test H3 $i\n"
  printf "# ################################ Test H2 $i\n"
 } > $file
 printf "$file\n" >> tests/output/multi/_list-complex.txt
done
```

--------------------------------

### Embed TOC in a JavaScript File

Source: https://github.com/alphajack/toc/blob/master/USAGE.md

Run `toc -f example.js` to embed a table of contents into the `example.js` file. The tool recognizes Node.js shebangs and places the TOC accordingly.

```bash
toc -f example.js
```

--------------------------------

### Release Steps: Update Version and Commit

Source: https://github.com/alphajack/toc/blob/master/CONTRIBUTING.md

Initial steps for a new release involve updating the version number in pyproject.toml and committing the changes.

```bash
git commit
```

--------------------------------

### Generate a Large Single File for Benchmarking

Source: https://github.com/alphajack/toc/blob/master/CONTRIBUTING.md

Creates a large text file with nested markdown headers for performance testing.

```bash
rm -f tests/output/longfile.txt
for i in {1..100000}; do
 {
  printf "# ################################################################ Test H1 $i\n"
  printf "# ################################ Test H2 $i\n"
 } >> tests/output/longfile.txt
done
```

--------------------------------

### Modified `example.js` Content with Updated TOC

Source: https://github.com/alphajack/toc/blob/master/USAGE.md

This is the content of `example.js` after new sections have been added and the TOC has been updated by the `toc` tool.

```javascript
#!/usr/bin/env node

// 
// Contents of example.js                                        
// 
// 
// 	Main section
// 		New section
// 			 Also New section
// 		New section
// 			 Also New section
// 		Nested section
// 			Nested section
// 				Nested section
// 					 Nested section
// 
// 

// ################################################################ Main section

let Section_1 = "Write //, 64 hash characters and the name of section"

// ################################ New section

let Section_1_1 = "Write //, 32 hash characters and the name of section"

// ################ Also New section

let Section_1_1_1 = "Write //, 32 hash characters and the name of section"

// ################################ New section

let Section_1_1 = "Write //, 32 hash characters and the name of section"

// ################ Also New section

let Section_1_1_1 = "Write //, 32 hash characters and the name of section"

// ################################ Nested section

let Section_1_2 = "Write //, 32 hash characters and the name of section"

// ################ Nested section

let Section_1_2_3 = "Write //, 16 hash characters and the name of section"

// ######## Nested section

let Section_1_2_4 = "Write //, 8 hash characters and the name of section"

// #### Nested section

let Section_1_2_5 = "Write //, 4 hash characters and the name of section"

```

--------------------------------

### Generate TOC with Line Numbers

Source: https://github.com/alphajack/toc/blob/master/USAGE.md

This code block displays the expected output of the 'toc -n example.js' command, showing a table of contents with line numbers.

```text
// ┌───────────────────────────────────────────────────────────────┐
// │ Contents of example.js                                        │
// ├───────────────────────────────────────────────────────────────┘
// │
// ├──┐Main section 19
// │  ├──┐New section 23
// │  │  └── Also New section 27
// │  ├──┐New section 31
// │  │  └── Also New section 35
// │  └──┐Nested section 39
// │     └──┐Nested section 43
// │        └──┐Nested section 47
// │           └── Nested section 51
// │
// └───────────────────────────────────────────────────────────────
```

--------------------------------

### Generate a Complex Large Single File for Benchmarking

Source: https://github.com/alphajack/toc/blob/master/CONTRIBUTING.md

Creates a large text file with more complex nested markdown headers for performance testing.

```bash
rm -f tests/output/longfile-complex.txt
for i in {1..100000}; do
 {
  printf "# ################################################################ Test H1 $i\n"
  printf "# ################################ Test H2 $i\n"
  printf "# ################ Test H3 $i\n"
  printf "# ################ Test H3 $i\n"
  printf "# ################################ Test H2 $i\n"
 } >> tests/output/longfile-complex.txt
done
```

--------------------------------

### LaTeX Headings

Source: https://github.com/alphajack/toc/blob/master/USAGE.md

Use LaTeX commands from \chapter to \subparagraph for sectioning.

```latex
\chapter{My chapter}

\section{First section of the chapter}
\subsection{First child of the section}

\section{Second section of the chapter}
```

--------------------------------

### Generate Table of Contents Output

Source: https://github.com/alphajack/toc/blob/master/USAGE.md

This is the expected stdout when running the 'toc' command on the 'example.js' file. It shows the generated table of contents based on the defined nested sections.

```javascript
// ┌───────────────────────────────────────────────────────────────┐
// │ Contents of example.js                                        │
// ├───────────────────────────────────────────────────────────────┘
// │
// ├──┐Main section
// │  └──┐Nested section
// │     └──┐Nested section
// │        └──┐Nested section
// │           └── Nested section
// │
// └───────────────────────────────────────────────────────────────

```

--------------------------------

### Run TOC with Specific Files

Source: https://github.com/alphajack/toc/blob/master/CONTRIBUTING.md

Execute the TOC command with the -lf flag to process specific .tocfiles.

```bash
toc -lf .tocfiles
```

--------------------------------

### Generate Reference File with TOC CLI

Source: https://github.com/alphajack/toc/blob/master/tests/reference/_README.md

This command generates a reference file using the TOC CLI. It specifies the output file path and the input file path.

```bash
file=name_of_file
./toc/cli.py -o "./tests/reference/$file" -f "./tests/input/$file"
```

--------------------------------

### Memory Allocation Profiling with memray

Source: https://github.com/alphajack/toc/blob/master/CONTRIBUTING.md

Employ memray to analyze memory allocation during code execution. This includes running the profiler, generating a summary, a call tree, and a flamegraph.

```bash
pip install memray
memray run -o "tests/output/prof_memray.bin" toc/cli.py "tests/output/longfile.txt"
memray summary "tests/output/prof_memray.bin"
memray tree "tests/output/prof_memray.bin"
memray flamegraph "tests/output/prof_memray.bin"
firefox "tests/output/memray-flamegraph-prof_memray.html"
rm "tests/output/memray.bin" "tests/output/memray-flamegraph-prof_memray.html"
```

--------------------------------

### Generate TOC with Limited Depth

Source: https://github.com/alphajack/toc/blob/master/USAGE.md

This code block displays the expected output of the 'toc -d 2 example.js' command, showing a table of contents with a limited depth.

```text
// ┌───────────────────────────────────────────────────────────────┐
// │ Contents of example.js                                        │
// ├───────────────────────────────────────────────────────────────┘
// │
// ├──┐Main section
// │  ├── New section
// │  ├── New section
// │  └── Nested section
// │
// └───────────────────────────────────────────────────────────────
```

--------------------------------

### Man Page Headings

Source: https://github.com/alphajack/toc/blob/master/USAGE.md

Use '.TH', '.SH', and '.Ss' indicators for headings in man pages.

```groff
.TH MAN 1 "2023-09-23" "2.12.0" "Manual pager utils"

.SH NAME
man \- an interface to the system reference manuals

.SH SYNOPSIS
." The general command line
```

--------------------------------

### Markdown Sectioning

Source: https://github.com/alphajack/toc/blob/master/USAGE.md

Use '#' for titles and '##' for sections in Markdown files.

```markdown
# Title
   
## Section
```

--------------------------------

### Release Steps: Move Tag

Source: https://github.com/alphajack/toc/blob/master/CONTRIBUTING.md

After pushing new commits, move the temporary tag to the latest commit to mark the release.

```bash
git tag -fa v2.6.0
```

--------------------------------

### Release Steps: Handle Failed Release

Source: https://github.com/alphajack/toc/blob/master/CONTRIBUTING.md

If a tag has been pushed but the release process fails, delete the remote tag and repeat the release steps.

```bash
git push --delete origin v2.6.0
```

--------------------------------

### Process All Files in Directory with Glob

Source: https://github.com/alphajack/toc/blob/master/USAGE.md

Run `toc *` to process all files in the current directory. The tool has several intelligent skipping mechanisms for directories, non-text files, and files that do not require updates.

```bash
toc *
```

--------------------------------

### Beancount Sectioning

Source: https://github.com/alphajack/toc/blob/master/USAGE.md

Use '*' for top-level sections and '**' for sub-sections in Beancount files.

```ini
* Options

; comment

* Transactions
** FY2020

2020-04-20 * "Food"
 Assets:Bank                                          -20.00 EUR
 Expenses:Groceries
```

--------------------------------

### Redirect Output to File

Source: https://github.com/alphajack/toc/blob/master/USAGE.md

Use the -o flag to specify a different output file for the generated table of contents. This option is useful for testing or organizing output.

```bash
toc -o output.py input.py
```

--------------------------------

### OCaml Multi-line Comments

Source: https://github.com/alphajack/toc/blob/master/USAGE.md

Wrap '*' comments with '(*' and '*)' in OCaml files for table of contents generation.

```ocaml
(*
* ################################################################ Unique section
*)

let () = print_endline "Hello, World!"
```

--------------------------------

### HTML Headings

Source: https://github.com/alphajack/toc/blob/master/USAGE.md

Use standard HTML heading tags like <h1> and <h2> for sectioning in HTML files.

```html
<!doctype html>
<html>
<h1>Title</h1>
<h2>Subtitle</h2>
</html>
```

--------------------------------

### Perl Pod Headings

Source: https://github.com/alphajack/toc/blob/master/USAGE.md

Use '=pod', '=head1', and '=head2' for headings in Perl Pod documentation.

```pod
=pod
=encoding utf8

=head1 Title

=head2 Section

=for comment
Text

=cut
```

--------------------------------

### Vim/Emacs Modeline Integration

Source: https://github.com/alphajack/toc/blob/master/USAGE.md

Place Vim modelines or Emacs mode lines as the first line in C files to enable toc appending.

```c
// vim: noai:ts=4:sw=4
#include <stdlib.h>

void main() { exit(0);}
```

--------------------------------

### Read from Stdin with Custom Extension

Source: https://github.com/alphajack/toc/blob/master/USAGE.md

Pipe content to 'toc' using '-' as the filename argument. The -e flag can be used to specify the file extension for parsing when reading from stdin.

```bash
curl -s https://github.com/AlphaJack/toc | toc -e html -
```

--------------------------------

### AsciiDoc Sectioning

Source: https://github.com/alphajack/toc/blob/master/USAGE.md

Use '=' for document titles and section headings in AsciiDoc files.

```adoc
= Document Title (Level 0)

== Level 1 Section Title

= Level 0 Section Title (Part)

== Level 1 Section Title

=== Level 2 Section Title

==== Level 3 Section Title

===== Level 4 Section Title

====== Level 5 Section Title
```

--------------------------------

### Release Steps: Remove Temporary Tag

Source: https://github.com/alphajack/toc/blob/master/CONTRIBUTING.md

Remove the temporary tag after it has been used to push the release and potentially moved to the correct commit.

```bash
git tag --delete v2.6.0
```

--------------------------------

### Typst Sectioning

Source: https://github.com/alphajack/toc/blob/master/USAGE.md

Use '=' for document titles and section headings in Typst files, similar to AsciiDoc.

```typst
= Introduction
= Background
== History
== State of the Art
= Analysis
== Setup
```

--------------------------------

### Modify cli.py for Profiling

Source: https://github.com/alphajack/toc/blob/master/CONTRIBUTING.md

This change is required for profiling tools to function correctly. Ensure you import the Toc class from the correct module.

```python
#from toc.toc import Toc
from toc import Toc
```

--------------------------------

### Define Nested Sections in JavaScript

Source: https://github.com/alphajack/toc/blob/master/USAGE.md

This JavaScript code demonstrates how to define nested sections using different lengths of hash characters for the 'toc' tool. Ensure your comments follow the '//' convention for JavaScript.

```javascript
#!/usr/bin/env node

// ################################################################ Main section

let Section1 = "Write //, 64 hash characters and the name of section"

// ################################ Nested section

let Section2 = "Write //, 32 hash characters and the name of section"

// ################ Nested section

let Section3 = "Write //, 16 hash characters and the name of section"

// ######## Nested section

let Section4 = "Write //, 8 hash characters and the name of section"

// #### Nested section

let Section5 = "Write //, 4 hash characters and the name of section"

```

--------------------------------

### Set Custom File Extension

Source: https://github.com/alphajack/toc/blob/master/USAGE.md

Use the -e flag to force 'toc' to consider a specific file extension, overriding its default detection. This is useful for files with non-standard extensions.

```bash
toc -e "html" new-file-format.html6
```

--------------------------------

### Show Line Numbers in TOC

Source: https://github.com/alphajack/toc/blob/master/USAGE.md

Use the -n flag to display line numbers for each section in the generated table of contents. This is useful for very long files.

```bash
toc -n example.js
```

--------------------------------

### reStructuredText Headings

Source: https://github.com/alphajack/toc/blob/master/USAGE.md

Use underline styles with characters like '*', '=', and '-' for sectioning in reStructuredText files.

```rst
*******
Chapter
*******

=======
Section
=======

----------
Subsection
----------
```

--------------------------------

### CSS Multi-line Comments

Source: https://github.com/alphajack/toc/blob/master/USAGE.md

Wrap '//' comments with '/*' and '*/' in CSS files when they need to be part of the table of contents.

```css
/*
// ################################################################ Landscape touchscreen
*/

@media (orientation: landscape) and (hover: none) and (pointer: coarse) {

/*
// ################################ Element selectors
*/

body {background-color: blue;}

} /* end Landscape touchscreen */
```

--------------------------------

### RStudio Foldable Comments

Source: https://github.com/alphajack/toc/blob/master/USAGE.md

End comments with at least 4 '-', '=', or '#' characters in R files to create foldable sections recognized by RStudio.

```r
# ################################################################ Foldable section 1 ####

print("Collapse me!")

# ################################ Foldable section 2 ####

print("Collapse me!")

```

--------------------------------

### Set Custom Comment Character

Source: https://github.com/alphajack/toc/blob/master/USAGE.md

Use the -c flag to specify a custom comment character if 'toc' does not automatically detect it for a given file type. This ensures correct parsing of comments.

```bash
toc -c "//" example.xyz
```

--------------------------------

### Limit TOC Depth

Source: https://github.com/alphajack/toc/blob/master/USAGE.md

Use the -d flag to limit the depth of the generated table of contents. This is useful for controlling the verbosity of the TOC.

```bash
toc -d 2 example.js
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.