Create ToC in markdown files for Catch2 documentation

catch-toclify.bat

@echo off & setlocal enableextensions
::
:: ./Catch-toclify.bat - ... (https://github.com/rasbt/markdown-toclify)
::
if [%1] == [] goto :Usage

set files= %*%

set root=%~dp0
set toclify=%root%\markdown-toclify.py

echo Converting:
for %%f in ( %files% ) do (
    echo "%%f
    python "%toclify%" --github --exclude_h 1,3 %%f -o %%f.tmp
    copy /y %%f.tmp %%f >nul
    del %%f.tmp
)
endlocal & goto :EOF

:Usage
echo %0 [file...]
endlocal & goto :EOF

rem
rem end of file
rem

catch-toclify.py

#
# catch-toclify.py - insert table of contents at top of Catch markdown documents
#
import os
import sys
import glob

heading_exclude_default = '1,3,4,5'
heading_exclude_release = '2,3,4,5'

release_notes = 'release-notes.md' 

def is_release_notes(f):
    return os.path.basename(f) == release_notes 

def exclude_headings_for(f):
    return heading_exclude_release if is_release_notes(f) else heading_exclude_default

def catch_toclify( toclify, paths ):
    for g in paths:
        for f in glob.glob(g):
            print( 'file: {}'.format(f))
            out = f+'.tmp'
            cmd = 'python "{toclify}" --github --exclude_h {exclude_h} {f} -o {out}'.format(
                toclify=toclify, exclude_h=exclude_headings_for(f), f=f, out=out )
#            print( 'cmd: {}'.format(cmd))
            os.system(cmd)
            os.remove(f)
            os.rename(out, f)

def usage(prog):
    print('{prog} [file...]'.format(prog=prog))
    return 0
    
if __name__ == '__main__':
    if len(sys.argv) <= 1:
        exit(usage(sys.argv[0]))
        
    files = sys.argv[1:]

    catch_toclify_dir = os.path.dirname(os.path.realpath(sys.argv[0]))
    markdown_toclify_name = 'markdown-toclify.py'
    
    catch_toclify(os.path.join(catch_toclify_dir, markdown_toclify_name), files)

# end of file

markdown-toclify.py

#!/usr/bin/env python

#
# Sebastian Raschka 2014-2015
#
# Python script that inserts a table of contents
# into markdown documents and creates the required
# internal links.
#
# For more information about how internal links
# in HTML and Markdown documents work, please see
#
# Creating a table of contents with internal links in
# IPython Notebooks and Markdown documents:
# http://sebastianraschka.com/Articles/2014_ipython_internal_links.html
#
# Updates for this script will be available at
# https://github.com/rasbt/markdown-toclify
#
# for more information about the usage:
# markdown-toclify.py --help
#

import argparse
import re


__version__ = '1.7.1'

VALIDS = '0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ_-&'


def read_lines(in_file):
    """Returns a list of lines from a input markdown file."""

    with open(in_file, 'r') as inf:
        in_contents = inf.read().split('\n')
    return in_contents


def remove_lines(lines, remove=('[[back to top]', '<a class="mk-toclify"')):
    """Removes existing [back to top] links and <a id> tags."""

    if not remove:
        return lines[:]

    out = []
    for l in lines:
        if l.startswith(remove):
            continue
        out.append(l)
    return out


def dashify_headline(line):
    """
    Takes a header line from a Markdown document and
    returns a tuple of the
        '#'-stripped version of the head line,
        a string version for <a id=''></a> anchor tags,
        and the level of the headline as integer.
    E.g.,
    >>> dashify_headline('### some header lvl3')
    ('Some header lvl3', 'some-header-lvl3', 3)

    """
    stripped_right = line.rstrip('#')
    stripped_both = stripped_right.lstrip('#')
    level = len(stripped_right) - len(stripped_both)
    stripped_wspace = stripped_both.strip()

    # character replacements
    replaced_colon = stripped_wspace.replace('.', '')
    replaced_slash = replaced_colon.replace('/', '')
    rem_nonvalids = ''.join([c if c in VALIDS
                             else '-' for c in replaced_slash])

    lowered = rem_nonvalids.lower()
    dashified = re.sub(r'(-)\1+', r'\1', lowered)  # remove duplicate dashes
    dashified = dashified.strip('-')  # strip dashes from start and end

    # exception '&' (double-dash in github)
    dashified = dashified.replace('-&-', '--')

    return [stripped_wspace, dashified, level]


def tag_and_collect(lines, id_tag=True, back_links=False, exclude_h=None):
    """
    Gets headlines from the markdown document and creates anchor tags.

    Keyword arguments:
        lines: a list of sublists where every sublist
            represents a line from a Markdown document.
        id_tag: if true, creates inserts a the <a id> tags (not req. by GitHub)
        back_links: if true, adds "back to top" links below each headline
        exclude_h: header levels to exclude. E.g., [2, 3]
            excludes level 2 and 3 headings.

    Returns a tuple of 2 lists:
        1st list:
            A modified version of the input list where
            <a id="some-header"></a> anchor tags where inserted
            above the header lines (if github is False).

        2nd list:
            A list of 3-value sublists, where the first value
            represents the heading, the second value the string
            that was inserted assigned to the IDs in the anchor tags,
            and the third value is an integer that reprents the headline level.
            E.g.,
            [['some header lvl3', 'some-header-lvl3', 3], ...]

    """
    out_contents = []
    headlines = []
    for l in lines:
        saw_headline = False

        orig_len = len(l)
# @CATCH l = l.lstrip()

# @CATCH if l.startswith(('# ', '## ', '### ', '#### ', '##### ', '###### ')):
        if l.strip().startswith(('# ', '## ', '### ', '#### ', '##### ', '###### ')):

            # comply with new markdown standards

            # not a headline if '#' not followed by whitespace '##no-header':
            if not l.lstrip('#').startswith(' '):
                continue
            # not a headline if more than 6 '#':
            if len(l) - len(l.lstrip('#')) > 6:
                continue
            # headers can be indented by at most 3 spaces:
# @CATCH    if orig_len - len(l) > 3:
            if orig_len - len(l.strip()) > 3:
                continue

            # ignore empty headers
            if not set(l) - {'#', ' '}:
                continue

            saw_headline = True
            dashified = dashify_headline(l)

            if not exclude_h or not dashified[-1] in exclude_h:
                if id_tag:
                    id_tag = '<a class="mk-toclify" id="%s"></a>'\
                              % (dashified[1])
                    out_contents.append(id_tag)
                headlines.append(dashified)

        out_contents.append(l)
        if back_links and saw_headline:
            out_contents.append('[[back to top](#table-of-contents)]')
    return out_contents, headlines


def positioning_headlines(headlines):
    """
    Strips unnecessary whitespaces/tabs if first header is not left-aligned
    """
    left_just = False
    for row in headlines:
        if row[-1] == 1:
            left_just = True
            break
    if not left_just:
        for row in headlines:
            row[-1] -= 1
    return headlines


def create_toc(headlines, hyperlink=True, top_link=False, no_toc_header=False):
    """
    Creates the table of contents from the headline list
    that was returned by the tag_and_collect function.

    Keyword Arguments:
        headlines: list of lists
            e.g., ['Some header lvl3', 'some-header-lvl3', 3]
        hyperlink: Creates hyperlinks in Markdown format if True,
            e.g., '- [Some header lvl1](#some-header-lvl1)'
        top_link: if True, add a id tag for linking the table
            of contents itself (for the back-to-top-links)
        no_toc_header: suppresses TOC header if True.

    Returns  a list of headlines for a table of contents
    in Markdown format,
    e.g., ['        - [Some header lvl3](#some-header-lvl3)', ...]

    """
    processed = []
    if not no_toc_header:
        if top_link:
            processed.append('<a class="mk-toclify" id="table-of-contents"></a>\n')
# @CATCH:
        processed.append('**Contents**  ')

    for line in headlines:
        if hyperlink:
            item = '[%s](#%s)  ' % (line[0], line[1])
# @CATCH    item = '%s- [%s](#%s)' % ((line[2]-1)*'    ', line[0], line[1])
        else:
            item = '%s- %s' % ((line[2]-1)*'    ', line[0])
        processed.append(item)
    processed.append('\n')
    return processed


def build_markdown(toc_headlines, body, spacer=0, placeholder=None):
    """
    Returns a string with the Markdown output contents incl.
    the table of contents.

    Keyword arguments:
        toc_headlines: lines for the table of contents
            as created by the create_toc function.
        body: contents of the Markdown file including
            ID-anchor tags as returned by the
            tag_and_collect function.
        spacer: Adds vertical space after the table
            of contents. Height in pixels.
        placeholder: If a placeholder string is provided, the placeholder
            will be replaced by the TOC instead of inserting the TOC at
            the top of the document

    """
    if spacer:
        spacer_line = ['\n<div style="height:%spx;"></div>\n' % (spacer)]
        toc_markdown = "\n".join(toc_headlines + spacer_line)
    else:
        toc_markdown = "\n".join(toc_headlines)

    body_markdown = "\n".join(body)
# @CATCH    body_markdown = "\n".join(body).strip()

    if placeholder:
        markdown = body_markdown.replace(placeholder, toc_markdown)
    else:
        markdown = toc_markdown + body_markdown

    return markdown


def output_markdown(markdown_cont, output_file):
    """
    Writes to an output file if `outfile` is a valid path.

    """
    if output_file:
        with open(output_file, 'w') as out:
            out.write(markdown_cont)


def markdown_toclify(input_file, output_file=None, github=False,
                     back_to_top=False, nolink=False,
                     no_toc_header=False, spacer=0, placeholder=None,
                     exclude_h=None):
    """ Function to add table of contents to markdown files.

    Parameters
    -----------
      input_file: str
        Path to the markdown input file.

      output_file: str (defaul: None)
        Path to the markdown output file.

      github: bool (default: False)
        Uses GitHub TOC syntax if True.

      back_to_top: bool (default: False)
        Inserts back-to-top links below headings if True.

      nolink: bool (default: False)
        Creates the table of contents without internal links if True.

      no_toc_header: bool (default: False)
        Suppresses the Table of Contents header if True

      spacer: int (default: 0)
        Inserts horizontal space (in pixels) after the table of contents.

      placeholder: str (default: None)
        Inserts the TOC at the placeholder string instead
        of inserting the TOC at the top of the document.

      exclude_h: list (default None)
        Excludes header levels, e.g., if [2, 3], ignores header
        levels 2 and 3 in the TOC.

    Returns
    -----------
    cont: str
      Markdown contents including the TOC.

    """
    raw_contents = read_lines(input_file)
    cleaned_contents = remove_lines(raw_contents, remove=('[[back to top]', '<a class="mk-toclify"'))
    processed_contents, raw_headlines = tag_and_collect(
                                            cleaned_contents,
                                            id_tag=not github,
                                            back_links=back_to_top,
                                            exclude_h=exclude_h,
                                            )

    leftjustified_headlines = positioning_headlines(raw_headlines)
    processed_headlines = create_toc(leftjustified_headlines,
                                     hyperlink=not nolink,
                                     top_link=not nolink and not github,
                                     no_toc_header=no_toc_header)

    if nolink:
        processed_contents = cleaned_contents

    cont = build_markdown(toc_headlines=processed_headlines,
                          body=processed_contents,
                          spacer=spacer,
                          placeholder=placeholder)

    if output_file:
        output_markdown(cont, output_file)
    return cont


def commandline():

    parser = argparse.ArgumentParser(
            description='Python script that inserts a table of contents\n'\
                    'into markdown documents and creates the required internal links.',
            epilog="""    Example:
    markdown-toclify.py ~/Desktop/input.md -o ~/Desktop/output.md

    For more information about how internal links in
    HTML and Markdown documents work
    please see:
    "Creating a table of contents with internal
     links in IPython Notebooks and Markdown documents"
    (http://sebastianraschka.com/Articles/2014_ipython_internal_links.html)

    Updates for this script will be available at
    https://github.com/rasbt/markdown-toclify

    """,
            formatter_class=argparse.RawTextHelpFormatter
    )

    parser.add_argument('InputFile',
                        metavar='input.md',
                        help='path to the Markdown input file')
    parser.add_argument('-o', '--output',
                        metavar='output.md',
                        default=None,
                        help='path to the Markdown output file')
    parser.add_argument('-b', '--back_to_top',
                        action='store_true',
                        help='add [back to top] links.')
    parser.add_argument('-g', '--github',
                        action='store_true',
                        help='omits id-anchor tags (recommended for GitHub)')
    parser.add_argument('-s', '--spacer',
                        default=0,
                        type=int,
                        metavar='pixels',
                        help='add horizontal space (in pixels) after the table of contents')
    parser.add_argument('-n', '--nolink',
                        action='store_true',
                        help='create the table of contents without internal links')
    parser.add_argument('-e', '--exclude_h',
                        type=str,
                        default='',
                        help='exclude eading levels, e.g., "2,3" to exclude all level 2 and 3 headings')
    parser.add_argument('--placeholder',
                        type=str,
                        help='inserts TOC at the placeholder string instead of inserting it on top of the document')
    parser.add_argument('--no_toc_header',
                        action='store_true',
                        help='suppresses the Table of Contents header')
    parser.add_argument('-v', '--version',
                        action='version',
                        version='%s' % __version__)

    args = parser.parse_args()

    if args.exclude_h:
        exclude_h = [int(i) for i in args.exclude_h.split(',')]
    else:
        exclude_h = None

    cont = markdown_toclify(input_file=args.InputFile,
                            output_file=args.output,
                            github=args.github,
                            back_to_top=args.back_to_top,
                            nolink=args.nolink,
                            no_toc_header=args.no_toc_header,
                            spacer=args.spacer,
                            placeholder=args.placeholder,
                            exclude_h=exclude_h)

    if not args.output:
        print(cont)

if __name__ == '__main__':
    commandline()