doctoc 0.0.1__tar.gz

doctoc-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 KtechHub
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

doctoc-0.0.1/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.1
+Name: doctoc
+Version: 0.0.1
+Summary: Generate table of contents for Markdown files
+Home-page: https://github.com/ktechhub/doctoc
+Author: Ktechhub
+Author-email: mm@ktechhub.com
+License: MIT
+Keywords: markdown table of contents
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.6
+Requires-Python: >=3.6
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click
+Requires-Dist: requests
+
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+
+**Table of Contents**  *generated with [DocToc](https://github.com/ktechhub/doctoc)*
+
+<!---toc start-->
+
+- [DocToc](#doctoc)
+  - [Prerequisites](#prerequisites)
+  - [Installation](#installation)
+  - [Usage](#usage)
+    - [Options:](#options)
+  - [Features](#features)
+  - [GitHub](#github)
+  - [License](#license)
+    - [Contribution](#contribution)
+
+<!---toc end-->
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+# DocToc
+DocToc is a command-line tool built with Python that automatically generates and updates table of contents (TOC) for Markdown files. It scans through your Markdown file, identifies headers, and creates a TOC with clickable links.
+
+## Prerequisites
+Before installing DocToc, ensure you have the following:
+- Python 3.6+
+- pip (Python package installer)
+
+## Installation
+You can install DocToc using pip:
+
+```sh
+pip install doctoc
+```
+Alternatively, you can install it from the source on GitHub:
+
+```sh
+git clone https://github.com/ktechhub/doctoc.git
+cd doctoc
+python setup.py install
+```
+
+## Usage
+Generate a table of contents for a Markdown file:
+
+```sh
+doctoc --help
+Usage: doctoc [OPTIONS] MARKDOWN_FILE
+
+  Generate or update a table of contents for Markdown files and optionally
+  check hyperlinks.
+
+  Args:
+  markdown_file (str): Path to the Markdown file to process.
+  outfile (str, optional): Output file path. If specified, writes the modified content to this file instead of overwriting the original.
+  check_links (bool): Flag to enable checking the validity of hyperlinks found in the Markdown file.
+
+Options:
+  -o, --outfile TEXT  Specify an output file instead of overwriting.
+  -cl, --check-links  Check validity of hyperlinks.
+  --help              Show this message and exit.
+```
+
+### Options:
+
+- `--outfile`: Specify an output file instead of overwriting.
+- `--check-links`: Check the validity of hyperlinks within the Markdown file.
+
+Example with options:
+```sh
+doctoc README.md --check-links
+```
+Output
+```sh
+Success: wrote TOC to README.md
+Checking hyperlinks...
+VALID: [DocToc](https://github.com/ktechhub/doctoc)
+VALID: [DocToc](#doctoc)
+VALID: [Prerequisites](#prerequisites)
+VALID: [Installation](#installation)
+VALID: [Usage](#usage)
+VALID: [Options:](#options)
+VALID: [Features](#features)
+VALID: [GitHub](#github)
+VALID: [License](#license)
+VALID: [GitHub repository](https://github.com/ktechhub/doctoc)
+```
+
+```sh
+doctoc README.md --outfile README_with_toc.md
+```
+Output
+```sh
+Success: wrote TOC to README_with_toc.md
+```
+```sh
+doctoc README.md --outfile README_with_toc.md --check-links
+```
+
+## Features
+- Automatically generates a TOC based on Markdown headers.
+- Supports customization with options to specify output file and check link validity.
+- Simple and easy to use with a command-line interface.
+
+## GitHub
+For more details, visit the [GitHub repository](https://github.com/ktechhub/doctoc).
+
+## License
+This project is licensed under the MIT License - see the LICENSE file for details.
+
+### Contribution
+If you want to contribute, kindly see this **[contribution](https://github.com/ktechhub/doctoc/tree/main/contribution.md)**

doctoc-0.0.1/README.md

@@ -0,0 +1,112 @@
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+
+**Table of Contents**  *generated with [DocToc](https://github.com/ktechhub/doctoc)*
+
+<!---toc start-->
+
+- [DocToc](#doctoc)
+  - [Prerequisites](#prerequisites)
+  - [Installation](#installation)
+  - [Usage](#usage)
+    - [Options:](#options)
+  - [Features](#features)
+  - [GitHub](#github)
+  - [License](#license)
+    - [Contribution](#contribution)
+
+<!---toc end-->
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+# DocToc
+DocToc is a command-line tool built with Python that automatically generates and updates table of contents (TOC) for Markdown files. It scans through your Markdown file, identifies headers, and creates a TOC with clickable links.
+
+## Prerequisites
+Before installing DocToc, ensure you have the following:
+- Python 3.6+
+- pip (Python package installer)
+
+## Installation
+You can install DocToc using pip:
+
+```sh
+pip install doctoc
+```
+Alternatively, you can install it from the source on GitHub:
+
+```sh
+git clone https://github.com/ktechhub/doctoc.git
+cd doctoc
+python setup.py install
+```
+
+## Usage
+Generate a table of contents for a Markdown file:
+
+```sh
+doctoc --help
+Usage: doctoc [OPTIONS] MARKDOWN_FILE
+
+  Generate or update a table of contents for Markdown files and optionally
+  check hyperlinks.
+
+  Args:
+  markdown_file (str): Path to the Markdown file to process.
+  outfile (str, optional): Output file path. If specified, writes the modified content to this file instead of overwriting the original.
+  check_links (bool): Flag to enable checking the validity of hyperlinks found in the Markdown file.
+
+Options:
+  -o, --outfile TEXT  Specify an output file instead of overwriting.
+  -cl, --check-links  Check validity of hyperlinks.
+  --help              Show this message and exit.
+```
+
+### Options:
+
+- `--outfile`: Specify an output file instead of overwriting.
+- `--check-links`: Check the validity of hyperlinks within the Markdown file.
+
+Example with options:
+```sh
+doctoc README.md --check-links
+```
+Output
+```sh
+Success: wrote TOC to README.md
+Checking hyperlinks...
+VALID: [DocToc](https://github.com/ktechhub/doctoc)
+VALID: [DocToc](#doctoc)
+VALID: [Prerequisites](#prerequisites)
+VALID: [Installation](#installation)
+VALID: [Usage](#usage)
+VALID: [Options:](#options)
+VALID: [Features](#features)
+VALID: [GitHub](#github)
+VALID: [License](#license)
+VALID: [GitHub repository](https://github.com/ktechhub/doctoc)
+```
+
+```sh
+doctoc README.md --outfile README_with_toc.md
+```
+Output
+```sh
+Success: wrote TOC to README_with_toc.md
+```
+```sh
+doctoc README.md --outfile README_with_toc.md --check-links
+```
+
+## Features
+- Automatically generates a TOC based on Markdown headers.
+- Supports customization with options to specify output file and check link validity.
+- Simple and easy to use with a command-line interface.
+
+## GitHub
+For more details, visit the [GitHub repository](https://github.com/ktechhub/doctoc).
+
+## License
+This project is licensed under the MIT License - see the LICENSE file for details.
+
+### Contribution
+If you want to contribute, kindly see this **[contribution](https://github.com/ktechhub/doctoc/tree/main/contribution.md)**

doctoc-0.0.1/doctoc/cli.py

@@ -0,0 +1,71 @@
+import click
+import os, sys
+import requests
+from .core import modify_and_write
+from .markdown import headers, get_links, as_link, MarkdownError
+
+
+@click.command()
+@click.argument("markdown_file")
+@click.option("--outfile", "-o", help="Specify an output file instead of overwriting.")
+@click.option(
+    "--check-links", "-cl", is_flag=True, help="Check validity of hyperlinks."
+)
+def main(markdown_file, outfile, check_links):
+    """
+    Generate or update a table of contents for Markdown files and optionally check hyperlinks.
+
+    Args:
+        markdown_file (str): Path to the Markdown file to process.
+        outfile (str, optional): Output file path. If specified, writes the modified content to this file instead of overwriting the original.
+        check_links (bool): Flag to enable checking the validity of hyperlinks found in the Markdown file.
+    """
+    try:
+        markdown_file = os.path.expanduser(markdown_file)
+        modify_and_write(markdown_file, outfile)
+
+        if check_links:
+            click.echo(click.style("Checking hyperlinks...", fg="yellow"), color=True)
+            with open(markdown_file) as fp:
+                contents = fp.read()
+
+            valid_http_fragments = ["#" + as_link(h) for (_, h) in headers(contents)]
+            for text, link, _, _ in get_links(contents):
+                if link.startswith("#"):
+                    if link not in valid_http_fragments:
+                        click.echo(
+                            click.style(f"INVALID: [{text}]({link})", fg="red"),
+                            color=True,
+                        )
+                    else:
+                        click.echo(
+                            click.style(f"VALID: [{text}]({link})", fg="green"),
+                            color=True,
+                        )
+                elif link.startswith("http://") or link.startswith("https://"):
+                    r = requests.get(link)
+                    click.echo(
+                        click.style(
+                            f"{'VALID' if r.status_code == 200 else 'INVALID'}: [{text}]({link})",
+                            fg="green" if r.status_code == 200 else "red",
+                        ),
+                        color=True,
+                    )
+                else:
+                    click.echo(
+                        click.style(
+                            f"UNRECOGNIZED LINK TYPE: [{text}]({link})", fg="yellow"
+                        ),
+                        color=True,
+                    )
+
+    except OSError as e:
+        click.echo(click.style(f"Failed: {e}", fg="red"), color=True)
+        sys.exit(1)
+    except MarkdownError as e:
+        click.echo(click.style(f"Failed: {e}", fg="red"), color=True)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

doctoc-0.0.1/doctoc/core.py

@@ -0,0 +1,47 @@
+import click
+from .markdown import toc
+
+TOC_START_TAG = (
+    "<!-- START doctoc generated TOC please keep comment here to allow auto update -->"
+)
+TOC_END_TAG = (
+    "<!-- END doctoc generated TOC please keep comment here to allow auto update -->"
+)
+
+
+def modify_and_write(path, outfile=None):
+
+    with open(path) as fp:
+        markdown = fp.read()
+
+    table_of_contents = toc(markdown)
+
+    start_index = markdown.find(TOC_START_TAG)
+    end_index = markdown.find(TOC_END_TAG) + len(TOC_END_TAG)
+
+    if start_index != -1 and end_index != -1:
+        new_markdown = (
+            markdown[:start_index]
+            + TOC_START_TAG
+            + "\n\n"
+            + f"**Table of Contents**  *generated with [DocToc](https://github.com/ktechhub/doctoc)*\n\n"
+            + f"<!---toc start-->\n\n{table_of_contents}\n\n<!---toc end-->\n\n"
+            + TOC_END_TAG
+            + "\n"
+            + markdown[end_index:]
+        )
+    else:
+        new_markdown = (
+            f"{TOC_START_TAG}\n"
+            f"<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->\n"
+            f"**Table of Contents**  *generated with [DocToc](https://github.com/ktechhub/doctoc)*\n\n"
+            f"<!---toc start-->\n\n{table_of_contents}\n\n<!---toc end-->\n\n"
+            f"{TOC_END_TAG}\n" + markdown
+        )
+
+    with open(outfile or path, "w") as fp:
+        fp.write(new_markdown)
+
+    click.echo(
+        click.style(f"Success: wrote TOC to {outfile or path}", fg="green"), color=True
+    )

doctoc-0.0.1/doctoc/markdown.py

@@ -0,0 +1,250 @@
+import re
+import collections
+
+TOC_PAT = re.compile(r"[ \t]*<!---toc start-->(.*?)<!---toc end-->\s*", flags=re.DOTALL)
+
+MD_LINK_PAT = re.compile(r"\[([^\[\]]+)\]\((([^\s)(]|\([^\s)(]*\))*)\)", re.M)
+
+HEADER_PAT = re.compile(r"^\s{,3}(#{1,6})\s+(.*)")
+
+STRIP_CANDIDATE_PAT = re.compile(r"(?<!\\)[ \t#]+$|^[ \t#]+")
+
+ITAL_PAT = re.compile(r"(?<!\\)_[^(?<!\\)_]+(?<!\\)_")
+BOLD_PAT = re.compile(r"(?<!\\)\*[^(?<!\\)\*]+(?<!\\)\*")
+
+
+class MarkdownError(Exception):
+    """Markdown formatted incorrectly & unparseable."""
+
+
+def _strip(x):
+    """
+    Strip surrounding spaces, tabs, and hash signs from the input string `x`.
+
+    This function removes leading and trailing whitespace characters (spaces and tabs),
+    as well as leading hash signs (`#`) from the input string `x`.
+
+    Args:
+        x (str): The input string from which surrounding spaces, tabs, and hash signs should be stripped.
+
+    Returns:
+        str: A modified version of the input string `x` with leading and trailing spaces, tabs,
+        and hash signs removed.
+
+    Example:
+        >>> _strip("  #  Hello, world!  #  ")
+        "Hello, world!"
+
+    Note:
+        This function assumes the existence of `STRIP_CANDIDATE_PAT`, which is a regular expression
+        pattern matching spaces, tabs, and hash signs. Ensure this pattern is defined and imported
+        in the context where this function is used.
+
+    """
+    return STRIP_CANDIDATE_PAT.sub("", x)
+
+
+def _replace_ital_bold(s):
+    """
+    Replace italic and bold formatting markers in the input string `s`.
+
+    This function iterates through occurrences of italic and bold patterns (represented by
+    `ITAL_PAT` and `BOLD_PAT` respectively) within the string `s`. It removes leading and trailing
+    underscore (`_`) and asterisk (`*`) characters from these patterns. This is useful when
+    processing Markdown text that includes inline formatting for italics and bold.
+
+    Args:
+        s (str): The input string where italic and bold markers need to be processed.
+
+    Returns:
+        str: A modified version of the input string `s` where italic and bold formatting markers
+        have been adjusted to remove leading and trailing underscore (`_`) and asterisk (`*`)
+        characters.
+
+    Example:
+        >>> _replace_ital_bold("_*italic and bold*_ text")
+        "italic and bold text"
+
+    Note:
+        This function assumes the existence of `ITAL_PAT` and `BOLD_PAT` patterns that match the
+        respective italic and bold formatting markers. Ensure these patterns are defined and
+        imported in the context where this function is used.
+    """
+    to_repl = "_*"
+    for pat in (ITAL_PAT, BOLD_PAT):
+        for match in pat.finditer(s):
+            found = match.group(0)
+            s = s.replace(found, found.strip(to_repl))
+    return s
+
+
+def as_link(x):
+    """
+    Convert a Markdown header string into a valid relative URL.
+
+    This function takes a Markdown header string, converts it to lowercase, removes special characters
+    except hyphens and underscores, replaces spaces with hyphens, and handles italics and bolds. It ensures
+    that resulting URLs are formatted correctly, particularly handling cases where the resulting string
+    ends with double hyphens by stripping one hyphen.
+
+    Args:
+        x (str): The input Markdown header string to convert into a URL.
+
+    Returns:
+        str: A valid relative URL converted from the input Markdown header string.
+
+    Example:
+        >>> as_link("Introduction to Markdown Syntax")
+        "introduction-to-markdown-syntax"
+
+    Note:
+        This function relies on the `_strip` and `_replace_ital_bold` helper functions to clean and format
+        the input string `x`. Ensure these functions are correctly defined and imported in the context
+        where this function is used.
+
+    """
+    res = re.sub(
+        r"[^-\w\s]",
+        "",
+        re.sub(r"\s+", "-", _strip(x.lower())),
+        flags=re.U,
+    )
+    res = _replace_ital_bold(res)
+
+    if res.endswith("--"):
+        res = res.strip("-") + "-"
+    return res
+
+
+def escape(x):
+    """
+    Escape square brackets '[' and ']'.
+
+    This function takes a string `x` and escapes square brackets '[' and ']' by replacing them with
+    their escaped counterparts '\\[' and '\\]'.
+
+    Args:
+        x (str): The input string containing square brackets '[' and/or ']'.
+
+    Returns:
+        str: The input string `x` with square brackets '[' and ']' escaped as '\\[' and '\\]'.
+
+    Example:
+        >>> escape("Example [String]")
+        "Example \\[String\\]"
+    """
+    return x.replace("[", "\\[").replace("]", "\\]")
+
+
+def get_links(md_string):
+    """
+    Find links in a Markdown string.
+
+    This function searches through a given Markdown string `md_string` for Markdown-style links
+    and yields tuples containing the link text, URL, line number, and column start index.
+
+    Args:
+        md_string (str): The Markdown string to search for links.
+
+    Yields:
+        tuple: A tuple containing four elements:
+            - link_text (str): The text of the Markdown link.
+            - link_url (str): The URL or target of the Markdown link.
+            - line_number (int): The line number in the Markdown string where the link was found (1-indexed).
+            - col_start (int): The column index in the line where the URL starts (0-indexed).
+    Example:
+        >>> md_string = "Here is a [sample link](https://example.com) in Markdown."
+        >>> list(get_links(md_string))
+        [('sample link', 'https://example.com', 1, 8)]
+
+    Notes:
+        - Assumes the Markdown links follow the format `[link_text](link_url)`.
+    """
+    lines = md_string.split("\n")
+    line_number = 0
+    for line in lines:
+        line_number += 1
+        for match in re.finditer(MD_LINK_PAT, line):
+            link_text = match.group(1)
+            link_url = match.group(2)
+            col_start = match.start(2)
+            yield link_text, link_url, line_number, col_start
+
+
+def toc(md_string):
+    """
+    Generate a table of contents for a Markdown string.
+
+    This function generates a table of contents (TOC) based on the headers found in the Markdown
+    string `md_string`. It iterates through the headers, converts each header to a link, and
+    formats it in Markdown syntax suitable for a TOC.
+
+    Args:
+        md_string (str): The Markdown string for which the TOC is to be generated.
+
+    Returns:
+        str: A Markdown-formatted string representing the table of contents.
+
+    Example:
+        >>> md_string = "# Header 1\n## Subheader 1.1\n### Subsubheader\n# Header 2"
+        >>> print(toc(md_string))
+        * [Header 1](#header-1)
+          * [Subheader 1.1](#subheader-11)
+            * [Subsubheader](#subsubheader)
+        * [Header 2](#header-2)
+
+    Notes:
+        - Assumes headers are marked with Markdown syntax (#, ##, ###, etc.).
+        - Uses `as_link`, `escape`, and `_strip` functions for link conversion and formatting.
+    """
+    toc = []
+    n_seen = collections.defaultdict(int)
+
+    for level, header in headers(md_string):
+        link = as_link(header)
+        n = n_seen[link]
+        if n > 0:
+            n_seen[link] += 1
+            link += "-" + str(n)
+        else:
+            n_seen[link] += 1
+
+        toc.append(
+            "{spaces}* [{header}](#{link})".format(
+                spaces="  " * (level - 1),
+                header=escape(_strip(header)),
+                link=link,
+            )
+        )
+    return "\n".join(toc)
+
+
+def headers(md_string):
+    """
+    Generate Markdown headers from a given Markdown string.
+
+    This function iterates through each line of the Markdown string `md_string`,
+    matches lines that start with Markdown header patterns defined in `HEADER_PAT`,
+    and yields tuples of header levels and header titles.
+
+    Args:
+        md_string (str): The Markdown string to extract headers from.
+
+    Yields:
+        tuple: A tuple containing the header level (int) and header title (str).
+
+    Example:
+        >>> md_string = "# Header 1\n## Subheader 1.1\n### Subsubheader\n# Header 2"
+        >>> list(headers(md_string))
+        [(1, 'Header 1'), (2, 'Subheader 1.1'), (3, 'Subsubheader'), (1, 'Header 2')]
+
+    Notes:
+        - Assumes headers are marked with Markdown syntax (#, ##, ###, etc.).
+        - Uses `HEADER_PAT` pattern for matching Markdown headers.
+    """
+    for line in md_string.split("\n"):
+        header = HEADER_PAT.match(line)
+        if header:
+            level = len(header.group(1))
+            header = header.group(2)
+            yield level, header

doctoc-0.0.1/doctoc.egg-info/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.1
+Name: doctoc
+Version: 0.0.1
+Summary: Generate table of contents for Markdown files
+Home-page: https://github.com/ktechhub/doctoc
+Author: Ktechhub
+Author-email: mm@ktechhub.com
+License: MIT
+Keywords: markdown table of contents
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.6
+Requires-Python: >=3.6
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click
+Requires-Dist: requests
+
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+
+**Table of Contents**  *generated with [DocToc](https://github.com/ktechhub/doctoc)*
+
+<!---toc start-->
+
+- [DocToc](#doctoc)
+  - [Prerequisites](#prerequisites)
+  - [Installation](#installation)
+  - [Usage](#usage)
+    - [Options:](#options)
+  - [Features](#features)
+  - [GitHub](#github)
+  - [License](#license)
+    - [Contribution](#contribution)
+
+<!---toc end-->
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+# DocToc
+DocToc is a command-line tool built with Python that automatically generates and updates table of contents (TOC) for Markdown files. It scans through your Markdown file, identifies headers, and creates a TOC with clickable links.
+
+## Prerequisites
+Before installing DocToc, ensure you have the following:
+- Python 3.6+
+- pip (Python package installer)
+
+## Installation
+You can install DocToc using pip:
+
+```sh
+pip install doctoc
+```
+Alternatively, you can install it from the source on GitHub:
+
+```sh
+git clone https://github.com/ktechhub/doctoc.git
+cd doctoc
+python setup.py install
+```
+
+## Usage
+Generate a table of contents for a Markdown file:
+
+```sh
+doctoc --help
+Usage: doctoc [OPTIONS] MARKDOWN_FILE
+
+  Generate or update a table of contents for Markdown files and optionally
+  check hyperlinks.
+
+  Args:
+  markdown_file (str): Path to the Markdown file to process.
+  outfile (str, optional): Output file path. If specified, writes the modified content to this file instead of overwriting the original.
+  check_links (bool): Flag to enable checking the validity of hyperlinks found in the Markdown file.
+
+Options:
+  -o, --outfile TEXT  Specify an output file instead of overwriting.
+  -cl, --check-links  Check validity of hyperlinks.
+  --help              Show this message and exit.
+```
+
+### Options:
+
+- `--outfile`: Specify an output file instead of overwriting.
+- `--check-links`: Check the validity of hyperlinks within the Markdown file.
+
+Example with options:
+```sh
+doctoc README.md --check-links
+```
+Output
+```sh
+Success: wrote TOC to README.md
+Checking hyperlinks...
+VALID: [DocToc](https://github.com/ktechhub/doctoc)
+VALID: [DocToc](#doctoc)
+VALID: [Prerequisites](#prerequisites)
+VALID: [Installation](#installation)
+VALID: [Usage](#usage)
+VALID: [Options:](#options)
+VALID: [Features](#features)
+VALID: [GitHub](#github)
+VALID: [License](#license)
+VALID: [GitHub repository](https://github.com/ktechhub/doctoc)
+```
+
+```sh
+doctoc README.md --outfile README_with_toc.md
+```
+Output
+```sh
+Success: wrote TOC to README_with_toc.md
+```
+```sh
+doctoc README.md --outfile README_with_toc.md --check-links
+```
+
+## Features
+- Automatically generates a TOC based on Markdown headers.
+- Supports customization with options to specify output file and check link validity.
+- Simple and easy to use with a command-line interface.
+
+## GitHub
+For more details, visit the [GitHub repository](https://github.com/ktechhub/doctoc).
+
+## License
+This project is licensed under the MIT License - see the LICENSE file for details.
+
+### Contribution
+If you want to contribute, kindly see this **[contribution](https://github.com/ktechhub/doctoc/tree/main/contribution.md)**

doctoc-0.0.1/doctoc.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+setup.py
+doctoc/__init__.py
+doctoc/cli.py
+doctoc/core.py
+doctoc/markdown.py
+doctoc.egg-info/PKG-INFO
+doctoc.egg-info/SOURCES.txt
+doctoc.egg-info/dependency_links.txt
+doctoc.egg-info/entry_points.txt
+doctoc.egg-info/requires.txt
+doctoc.egg-info/top_level.txt
+tests/test_doctoc.py

doctoc-0.0.1/doctoc.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

doctoc-0.0.1/doctoc.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+doctoc = doctoc.cli:main

doctoc-0.0.1/doctoc.egg-info/requires.txt

@@ -0,0 +1,2 @@
+click
+requests

doctoc-0.0.1/doctoc.egg-info/top_level.txt

@@ -0,0 +1 @@
+doctoc

doctoc-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

doctoc-0.0.1/setup.py

@@ -0,0 +1,57 @@
+"""
+A setuptools based setup module.
+See:
+https://www.ktechhub.com/tutorials/how-to-package-a-python-code-and-upload-to-pypi
+https://packaging.python.org/en/latest/distributing.html
+https://github.com/pypa/sampleproject
+"""
+
+import io
+from os import path, getenv
+from setuptools import setup, find_packages
+
+VERSION = getenv("VERSION", "0.0.1")  # package version
+if "v" in VERSION:
+    VERSION = VERSION[1:]
+
+here = path.abspath(path.dirname(__file__))
+# Get the long description from the README file
+with io.open(path.join(here, "README.md"), encoding="utf-8") as f:
+    long_description = "\n" + f.read()
+
+REQUIRES_PYTHON = ">=3.6"
+
+setup(
+    name="doctoc",
+    version=VERSION,
+    packages=find_packages(exclude=["tests", "docs", ".github"]),
+    install_requires=["click", "requests"],
+    entry_points={
+        "console_scripts": [
+            "doctoc = doctoc.cli:main",
+        ],
+    },
+    test_suite="tests",
+    python_requires=REQUIRES_PYTHON,
+    author="Ktechhub",
+    author_email="mm@ktechhub.com",
+    description="Generate table of contents for Markdown files",
+    long_description=long_description,
+    long_description_content_type="text/markdown",
+    url="https://github.com/ktechhub/doctoc",
+    license="MIT",
+    classifiers=[
+        "License :: OSI Approved :: MIT License",
+        "Intended Audience :: Developers",
+        "Programming Language :: Python :: 3.12",
+        "Programming Language :: Python :: 3.11",
+        "Programming Language :: Python :: 3.10",
+        "Programming Language :: Python :: 3.9",
+        "Programming Language :: Python :: 3.8",
+        "Programming Language :: Python :: 3.7",
+        "Programming Language :: Python :: 3.6",
+    ],
+    keywords="markdown table of contents",
+    setup_requires=["wheel"],
+    include_package_data=True,
+)

doctoc-0.0.1/tests/test_doctoc.py

@@ -0,0 +1,40 @@
+import pytest
+from doctoc.markdown import toc, headers, get_links, as_link, escape
+from doctoc.core import modify_and_write
+
+
+@pytest.fixture
+def sample_markdown():
+    return """
+    # Title 1
+    
+    ## Subtitle 1.1
+    
+    ### Sub-subtitle 1.1.1
+    """
+
+
+def test_modify_and_write(tmp_path):
+    markdown_file = tmp_path / "test.md"
+    markdown_file.write_text("# Title 1\n\n## Subtitle 1.1\n")
+
+    modify_and_write(markdown_file)
+    assert markdown_file.read_text().startswith(
+        "<!-- START doctoc generated TOC please keep comment here to allow auto update -->"
+    )
+
+
+def test_get_links():
+    md_string = "[Link](#header)"
+    links = list(get_links(md_string))
+    assert len(links) == 1
+    assert links[0][0] == "Link"
+    assert links[0][1] == "#header"
+
+
+def test_as_link():
+    assert as_link("Header with spaces") == "header-with-spaces"
+
+
+if __name__ == "__main__":
+    pytest.main()