Skip to main content
Warning: You are using the test version of PyPI. This is a pre-production deployment of Warehouse. Changes made here affect the production instance of TestPyPI (testpypi.python.org).
Help us improve Python packaging - Donate today!

Excerpt Markdown Style Comments From a File

Project Description

Introduction

Ever read or wrote source files containing sectioning comments? Especially in scientific and/or data analysis scripts I see a lot like

### Collect Data

or

###
### Remove Outliers
###

or even

### 2.1 Descriptive Statistics

(RStudio, an IDE for the programming language R has even come up with their own code sectioning and folding feature that requires comments like

# Hypothesis Testing ----

)

If these comments are markdown style section comments, we can excerpt them and set a table of contents.

A First Example

Suppose you have the following code:

#!/usr/bin/env python3

# #% A Tutorial Introduction

# ##% Getting Started

# no need to import anything
print('hello, world')

# ###% The First Python Function
def main():
    print('hello, world')


main()

# ##% Variables and Arithmetic Expressions
print('some code')

# a comment
print('more code')

We can excerpt the comments marked by ‘%’:

# A Tutorial Introduction
## Getting Started
### The First Python Function
## Variables and Arithmetic Expressions

which is valid markdown that we can convert using pandoc .

A Bit More Elaborated

Suppose you have a file ‘tests/files/some_file.txt’ reading:

#######% % All About Me
#######% % Me
####### The above defines a pandoc markdown header.
####### This is more text that will not be extracted.
#######% **This** is an example of a markdown paragraph: markdown
#######% recognizes only six levels of heading, so we use seven or
#######% more levels to mark "normal" text.
#######% Here you can use the full markdown
#######% [syntax](http://daringfireball.net/projects/markdown/syntax).
#######% *Note* the trailing line: markdown needs an empty line to end
#######% a paragraph.
#######%

#% A section
##% A subsection
### Not a subsubsection but a plain comment.
############% Another markdown paragraph.
############%
####### More text that will not be extracted.

Then excerpting the marked comments via

import excerpts
file_name = 'tests/files/some_file.txt'
with open(file_name) as infile:
    lines = infile.readlines()

excerpted = excerpts.excerpt(lines = lines, comment_character="#",
    magic_character="%")
print (''.join(str(p) for p in excerpted))

gives

% All About Me
% Me
**This** is an example of a markdown paragraph: markdown
recognizes only six levels of heading, so we use seven or
more levels to mark "normal" text.
Here you can use the full markdown
[syntax](http://daringfireball.net/projects/markdown/syntax).
*Note* the trailing line: markdown needs an empty line to end
a paragraph.

# A section
## A subsection
Another markdown paragraph.

which again is valid markdown for pandoc .

Working with Files

If you want to excerpt from a file and run pandoc on the result, you can use

excerpts.excerpts(file_name = file_name, comment_character="#",
    magic_character="%", output_path="output", run_pandoc=True,
    pandoc_formats="html")

to generate this file.

Command Line Interface

Excerpts has a command line interface that you may call from your operating systems’ command line instead of from python3:

usage: excerpts [-h] [-O OUTPUT_PATH] [-o POSTFIX] [-e PREFIX]
                [-c COMMENT_CHARACTER] [-m MAGIC_CHARACTER] [-v] [-x]
[-p]
                [-n] [-l] [--no-latex] [--formats PANDOC_FORMATS]
[--no-pep8]
                file

excerpt markdown-style comments from a file to markdown and

PEP8

PEP8 requires each “line of a block comment starts with a # and a single space”. excerpts takes care of this requirement by removing a single comment character that is followed by a space and a sequence of comments characters. Should you need to disable this behaviour, you can set allow_pep8 to False.

Requirements

Excerpts needs python3.

Installation

Try
pip3 install git+git://github.com/fvafrcu/excerpts –upgrade –user
Release History

Release History

This version
History Node

1.1.0

History Node

1.0.0

History Node

0.16.2

History Node

0.16.1

History Node

0.16.0

History Node

0.14.2

History Node

0.14.1

History Node

0.14.0

History Node

0.13.3

History Node

0.13.1

History Node

0.13.0

History Node

0.12.1

History Node

0.12.0

History Node

0.11.0

History Node

0.10.1

History Node

0.10.0

History Node

0.9.1

History Node

0.9.0

History Node

0.6.0

History Node

0.4.1

Download Files

Download Files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
excerpts-1.1.0-py3-none-any.whl (11.5 kB) Copy SHA256 Checksum SHA256 py3 Wheel May 21, 2017
excerpts-1.1.0.tar.gz (167.2 kB) Copy SHA256 Checksum SHA256 Source May 21, 2017

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting