placeholder, pip, exclude_h

CHANGELOG → CHANGELOG.txt

@@ -1,6 +1,17 @@
 CHANGELOG
 =========
 
+Version 1.7.0
+----------------
+
+- added --exlude_h argument to exclude specified header levels from the table of contents.
+- added --placeholder argument to insert the table of contents at a particular
+  position in the document.
+- added --no_toc_header argument to suppress the table of contents header
+- added markdown_toclify wrapper function and added markdown_toclify.
+  as module to PyPI.
+
+
 Version 1.6.0
 ----------------
 

README.md

@@ -3,39 +3,50 @@ markdown-toclify
 
 markdown_toclify.py is a Python command line script that adds a **Table of Contents** with internal section-links to Markdown documents.
 
-**Compatible with [Standard Markdown](http://standardmarkdown.com).**
+This project is hosted at: [https://github.com/rasbt/markdown-toclify](https://github.com/rasbt/markdown-toclify).
+
+**Compatible to [CommonMark](http://standardmarkdown.com) (formerly known as Common Markdown).**
+
+Sebastian Raschka 2014-2015
 
 
 <hr>
 
 
 - [Usage](#usage)
-    - [Optional arguments](#optional-arguments)
+    - [Command line arguments](#command-line-arguments)
+    - [Using the Python module](#useing-the-python-module)
 - [Examples](#examples)
-    - [Input file](#input-file)
-    - [Simple output file](#simple-output-file)
+    - [Basic usage](#basic-usage) 
+    	- [Input file](#input-file)
+    	- [Simple output file](#simple-output-file)
+    - [Advanced options](#advanced-options)
     - [Output file with back-to-top links and vertical space](#output-file-with-back-to-top-links-and-vertical-space)
-
+    - [Heading level exclusion](#output-file-with-back-to-top-links-and-vertical-space)
+    - [TOC insertion at a placeholder position](#toc-insertion-at-a-placeholder-position)
+
 <hr>
 
 **Requires:**  
 
 - [Python 2.7.x or 3.x](https://www.python.org/downloads/)
 - [argparse](https://pypi.python.org/pypi/argparse)
 
-
+<br>
 
 # Usage
 [[back to top](#markdown-toclify)]
 
-The usage is quite simple, you just need to provide a Markdown-formatted input file and the modified Markdown contents will be printed to the standard output screen. 
+You can simply copy the stand_alone script [./markdown_toclify/markdown_toclify.py](./markdown_toclify/markdown_toclify.py) to a local directory on your computer and use it from there.
+
+The basic usage is quite simple, you just need to provide a Markdown-formatted input file and the modified Markdown contents will be printed to the standard output screen. 
 
 
 	./markdown_toclify.py input.md
 
 <br>
 
-## Optional arguments
+## Command line arguments
 [[back to top](#markdown-toclify)]
 
 <pre>positional arguments:
@@ -50,9 +61,36 @@ optional arguments:
   -s pixels, --spacer pixels
                         add horizontal space (in pixels) after the table of contents
   -n, --nolink          create the table of contents without internal links
+  -e EXCLUDE_H, --exclude_h EXCLUDE_H
+                        exclude eading levels, e.g., "2,3" to exclude all level 2 and 3 headings
+  --placeholder PLACEHOLDER
+                        inserts TOC at the placeholder string instead of inserting it on top of the document
+  --no_toc_header       suppresses the Table of Contents header
   -v, --version         show program's version number and exit
 </pre>
 
+<br>
+<br>
+
+## Using the Python module
+[[back to top](#markdown-toclify)]
+
+Alternatively, markdown_toclify can be installed via pip
+
+	pip install markdown_toclify
+
+and used from the command line as 
+
+	python -m markown_toclify -h
+
+Furthermore, markown_toclify can also be imported as module and be used within Python. For example,
+
+    from markdown_toclify import markdown_toclify
+    cont = markdown_toclify(input_file='/Users/sebastian/Desktop/test_input.md')
+
+The markdown_toclify module has the same functionality as the command line tool. For more information about the usage, please refer to the help function via
+
+    help(markdown_toclify)
 
 <br>
 <br>
@@ -63,15 +101,19 @@ optional arguments:
 <br>
 <br>
 
-## Input file
+## Basic usage
+
+<br>
+
+### Input file
 [[back to top](#markdown-toclify)]
 
-![Input file](./images/test_input.png)
+![Input file](./images/test_input_1.png)
 
 <br>
 <br>
 
-## Simple output file
+### Simple output file
 [[back to top](#markdown-toclify)]
 
 Command:
@@ -86,7 +128,13 @@ Command:
 <br>
 <br>
 
-## Output file with back-to-top links and vertical space
+
+## Advanced options
+
+<br>
+
+
+### Output file with back-to-top links and vertical space
 [[back to top](#markdown-toclify)]
 
 Command:
@@ -97,3 +145,45 @@ Command:
 
 ![Output file 2](./images/test_output_2.png)
 
+
+<br>
+<br>
+
+### Heading level exclusion
+[[back to top](#markdown-toclify)]
+
+Command:
+
+	./markdown_toclify.py test_input_2.md -o test2_output.md --exlude_h 2,3
+
+
+**Input**
+<br>
+
+![Input file 2](./images/test_input_2.png)
+
+**Output**
+
+![Output file 3](./images/test_output_3.png)
+
+<br>
+<br>
+
+### TOC insertion at a placeholder position
+[[back to top](#markdown-toclify)]
+
+Command:
+
+	./markdown_toclify.py test_input_3.md -o test3_output.md --placeholder ??placeholder??
+
+
+**Input**
+<br>
+
+![Input file 3](./images/test_input_3.png)
+
+**Output**
+
+![Output file 4](./images/test_output_4.png)
+
+

example_markdown/test_input_2.md

@@ -0,0 +1,16 @@
+
+# Heading lvl 1
+
+"Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum."
+
+## Heading lvl 2
+
+"Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum."
+
+### Heading lvl 3
+"Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum."
+
+
+# Another Heading lvl 1
+
+"Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum."

example_markdown/test_input_3.md

@@ -0,0 +1,14 @@
+
+# Heading lvl 1
+
+"Lorem said dolor sit amet, ...
+
+## Heading lvl 2
+
+"Lorem ipsum dolor sit amet, ...
+
+??placeholder??
+
+### Heading lvl 3
+"Lorem ipsum dolor sit amet, ...
+

markdown_toclify/__init__.py

@@ -0,0 +1,12 @@
+# Sebastian Raschka 2014-2015
+# markdown-toclify
+
+from .markdown_toclify import markdown_toclify
+from .markdown_toclify import tag_and_collect
+from .markdown_toclify import create_toc
+from .markdown_toclify import positioning_headlines
+from .markdown_toclify import dashify_headline
+from .markdown_toclify import remove_lines
+
+__version__ = '0.1.7'
+

markdown_toclify/__main__.py

@@ -0,0 +1,7 @@
+# Sebastian Raschka 2014-2015
+# markdown-toclify
+
+from .markdown_toclify import commandline
+
+commandline()
+