openstack
/
deb-python-misaka
Code Issues Proposed changes

Update documentation.

This commit is contained in:
Frank Smit 2015-10-21 19:14:03 +02:00
parent e85b4ef75e
commit 2a46ce9677
5 changed files with 178 additions and 230 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

58
docs/_static/customizations.css vendored
View File

@ -1,58 +1,4 @@
body {
font-family: 'Liberation Sans', 'Nimbus Sans L', FreeSans,
'Helvetica Neue', Helvetica, Arial, sans-serif;
}
div.body h1, div.body h2, div.body h3, div.body h4, div.body h5, div.body h6 {
font-family: 'PT Serif', 'Droid Serif', 'DejaVu Serif', serif;
}
ul, div.sphinxsidebar ul, div.sphinxsidebar ul ul, div.sphinxsidebar ul.want-points {
list-style-type: none;
margin-left: 1em;
}
ul li:before {
content: '-';
position: relative;
left: -5px;
}
ul li {
text-indent: -5px;
}
.field-list ul {
padding-left: 0;
}
.field-list li:before {
content: '';
position: inherit;
left: 0;
}
.field-list li {
text-indent: 0;
}
pre {
padding: 7px 10px;
}
code {
background: transparent;
}
pre, code {
div[class^='highlight'] pre {
font-family: 'M+ 1m', 'Droid Sans Mono', 'DejaVu Sans Mono', monospace;
font-size: 14px;
}
table.docutils {
border: 0;
box-shadow: none;
}
table.docutils th {
border-width: 0 0 2px;
}
table.docutils td {
border-width: 0;
}
table.docutils tbody tr.row-odd { background: transparent }
table.docutils tbody tr.row-even { background: #ecf0f3 }

5
docs/changelog.rst
View File

@ -6,10 +6,13 @@ Changelog
Date format is year-month-day.
2.0.0b2 (2015-08-??)
2.0.0b2 (2015-10-??)
^^^^^^^^^^^^^^^^^^^^
- Rename ``Markdown.render`` to ``Markdown.__call__``.
- Add a bechmark testcase to chibitest.
- Simplify arguments of ``list``, ``list_item``, ``autolink`` and
``table_cell`` render callbacks.
2.0.0b1 (2015-07-18)

38
docs/conf.py
View File

@ -16,7 +16,9 @@ import sys
import os
import shlex
import alabaster
import sphinx_rtd_theme
html_theme = 'sphinx_rtd_theme'
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
@ -34,7 +36,6 @@ sys.path.insert(0, os.path.abspath('..'))
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.napoleon',
'alabaster',
]
# Add any paths that contain templates here, relative to this directory.
@ -114,24 +115,15 @@ todo_include_todos = False
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
html_theme = 'alabaster'
# html_theme = 'alabaster'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
html_theme_options = {
'github_user': 'FSX',
'github_repo': 'misaka',
'github_button': 'true',
'travis_button': 'true',
'gratipay_user': 'FSX',
'description': """\
Misaka is a CFFI-based binding for Hoedown, a fast markdown processing library
written in C.""",
}
html_theme_options = {}
# Add any paths that contain custom themes here, relative to this directory.
html_theme_path = [alabaster.get_path()]
# html_theme_path = [alabaster.get_path()]
# The name for this set of Sphinx documents. If None, it defaults to
# "<project> v<release> documentation".
@ -168,15 +160,15 @@ html_static_path = ['_static']
#html_use_smartypants = True
# Custom sidebar templates, maps document names to template names.
html_sidebars = {
'**': [
'about.html',
# 'navigation.html',
# 'relations.html',
# 'searchbox.html',
# 'donate.html',
]
}
# html_sidebars = {
# '**': [
# 'about.html',
# # 'navigation.html',
# # 'relations.html',
# # 'searchbox.html',
# # 'donate.html',
# ]
# }
# Additional templates that should be rendered to pages, maps page names to
# template names.

291
docs/index.rst
View File

@ -1,62 +1,37 @@
.. py:currentmodule:: misaka
.. Documentation
.. =============
Misaka
======
Misaka is a CFFI-based binding for Hoedown_, a fast markdown processing library
written in C. It features a fast HTML renderer and functionality to make custom
renderers (e.g. man pages or LaTeX).
Features:
- Works on CPython 2.7, 3.2, 3.3, 3.4 and PyPy 2.6+.
- Includes Smartypants for transforming characters into HTML entities.
Changelog
---------
**2.0.0b2 (2015-08-??)**
- Rename ``Markdown.render`` to ``Markdown.__call__``.
**2.0.0b1 (2015-07-18)**
- Rewrite. CFFI_ and Hoedown_ instead of Cython_ and Sundown_.
- Remove pre- and postprocessor support.
- Smartypants is a normal function instead of a postprocessor.
- Documentation now uses Sphinx_.
See the full changelog at :doc:`/changelog`.
See the :doc:`/changelog` for all changes.
.. _Hoedown: https://github.com/hoedown/hoedown
.. _Sundown: https://github.com/vmg/sundown
.. _CFFI: https://cffi.readthedocs.org
.. _Cython: http://cython.org/
.. _Sphinx: http://sphinx-doc.org
Installation
------------
Misaka has been tested on CPython 2.7, 3.2, 3.3, 3.4 and PyPy 2.6. It needs
CFFI 1.0 or newer, because of this it will not work on PyPy 2.5 and older.
Misaka has been tested on CPython 2.7, 3.2, 3.3, 3.4, 3.5 and PyPy 2.6.
CFFI 1.0 or newer is required. This means Misaka will not work on PyPy 2.5
and older versions.
With pip::
Install with pip::
pip install misaka
Or the lastest development version from Github::
Or grab the source from Github::
git clone https://github.com/FSX/misaka.git
cd misaka
python setup.py install
And run the tests::
Consult the `CFFI documentation`_ if you experience problems installing CFFI.
python setup.py test # or...
python tests/run_tests.py
.. _CFFI documentation: https://cffi.readthedocs.org/en/latest/installation.html
Usage
@ -64,6 +39,13 @@ Usage
Very simple example:
.. code:: python
import misaka as m
print m.html('some other text')
Or:
.. code:: python
from misaka import Markdown, HtmlRenderer
@ -73,13 +55,6 @@ Very simple example:
print md('some text')
Or:
.. code:: python
import misaka as m
print m.html('some other text')
Here's a simple example that uses Pygments_ to highlight code (houdini_ is
used to escape the HTML):
@ -103,7 +78,7 @@ used to escape the HTML):
return highlight(text, lexer, formatter)
renderer = HighlighterRenderer()
md = m.Markdown(renderer, extensions=m.EXT_FENCED_CODE)
md = m.Markdown(renderer, extensions=('fenced-code',))
print(md("""
Here is some code:
@ -125,65 +100,135 @@ for a renderer with all its methods implemented.
.. _houdini: https://github.com/FSX/houdini.py
Tests
-----
tidy_ is needed to run the tests. tox_ can be used to run the tests on
all supported Python versions with one command.
Run one of the following commands to install tidy::
apt-get install tidy # Debian and derivatives
pacman -S tidyhtml # Arch Linux
And run the tests with::
python setup.py test
It's also possible to include or exclude tests. ``-i`` and ``-e`` accept a
comma separated list of testcases::
# Only run MarkdownConformanceTest_10
python setup.py test -i MarkdownConformanceTest_10
# Or everything except MarkdownConformanceTest_10
python setup.py test -e MarkdownConformanceTest_10
# Or everything except MarkdownConformanceTest_10 and MarkdownConformanceTest_103
python setup.py test -e MarkdownConformanceTest_10,MarkdownConformanceTest_103
``-l`` prints a list of all testcases::
$ python setup.py test -l
[... build output ...]
MarkdownConformanceTest_10
MarkdownConformanceTest_103
BenchmarkLibraries
ArgsToIntTest
CustomRendererTest
SmartypantsTest
And ``-b`` runs benchmarks (``-i`` and ``-e`` can also be used in
combination with ``-b``)::
$ python setup.py test -b
[... build output ...]
>> BenchmarkLibraries
test_hoep 3270 1.00 s/t 305.91 us/op
test_markdown 20 1.23 s/t 61.44 ms/op
test_markdown2 10 3.29 s/t 329.34 ms/op
test_misaka 3580 1.00 s/t 280.01 us/op
test_misaka_classes 3190 1.00 s/t 314.00 us/op
test_mistune 70 1.04 s/t 14.91 ms/o
What you see in the above output are the name, repetitions, total amount of
time (in seconds) and the time taken for an operation (one repetition).
A benchmark tries to stay within one second and runs a test for a minimum
of ten repetitions and tries another ten if there's time left.
.. _tidy: http://tidy.sourceforge.net
.. _tox: https://testrun.org/tox/
API
---
Extensions
^^^^^^^^^^
.. py:data:: EXT_TABLES
.. py:data:: EXT_FENCED_CODE
.. py:data:: EXT_FOOTNOTES
.. py:data:: EXT_AUTOLINK
.. py:data:: EXT_STRIKETHROUGH
.. py:data:: EXT_UNDERLINE
.. py:data:: EXT_HIGHLIGHT
.. py:data:: EXT_QUOTE
.. py:data:: EXT_SUPERSCRIPT
.. py:data:: EXT_MATH
.. py:data:: EXT_NO_INTRA_EMPHASIS
.. py:data:: EXT_SPACE_HEADERS
.. py:data:: EXT_MATH_EXPLICIT
.. py:data:: EXT_DISABLE_INDENTED_CODE
====================== ==========================
Name Constant
====================== ==========================
tables EXT_TABLES
fenced-code EXT_FENCED_CODE
footnotes EXT_FOOTNOTES
autolink EXT_AUTOLINK
strikethrough EXT_STRIKETHROUGH
underline EXT_UNDERLINE
highlight EXT_HIGHLIGHT
quote EXT_QUOTE
superscript EXT_SUPERSCRIPT
math EXT_MATH
no-intra-emphasis EXT_NO_INTRA_EMPHASIS
space-headers EXT_SPACE_HEADERS
math-explicit EXT_MATH_EXPLICIT
disable-indented-code EXT_DISABLE_INDENTED_CODE
====================== ==========================
HTML render flags
^^^^^^^^^^^^^^^^^
.. py:data:: HTML_SKIP_HTML
.. py:data:: HTML_ESCAPE
.. py:data:: HTML_HARD_WRAP
.. py:data:: HTML_USE_XHTML
========== ==============
Name Constant
========== ==============
skip-html HTML_SKIP_HTML
escape HTML_ESCAPE
hard-wrap HTML_HARD_WRAP
use-xhtml HTML_USE_XHTML
========== ==============
Render method flags
^^^^^^^^^^^^^^^^^^^
Functions
^^^^^^^^^
These constants are passed to individual render methods as flags.
.. autofunction:: html
.. py:data:: LIST_ORDERED
.. py:data:: LI_BLOCK
.. py:data:: TABLE_ALIGN_LEFT
.. py:data:: TABLE_ALIGN_RIGHT
.. py:data:: TABLE_ALIGN_CENTER
.. py:data:: TABLE_ALIGNMASK
.. py:data:: TABLE_HEADER
.. py:data:: AUTOLINK_NORMAL
.. py:data:: AUTOLINK_EMAIL
.. autofunction:: smartypants
Classes
^^^^^^^
.. autoclass:: Markdown
:members:
.. autoclass:: HtmlRenderer
:members:
.. autoclass:: HtmlTocRenderer
:members:
.. autoclass:: BaseRenderer
.. py:method:: blockcode(text, lang='')
``lang`` contains the language when fenced code blocks
(:py:const:`EXT_FENCED_CODE`) are enabled and a language is
defined in ther code block.
are enabled and a language is defined in ther code block.
.. py:method:: blockquote(content)
@ -193,85 +238,51 @@ Classes
.. py:method:: hrule()
.. py:method:: list(content, flags=0)
.. py:method:: list(content, is_ordered, is_block)
``flags`` can contain the following flags:
- :py:const:`LIST_ORDERED`: An ordered list.
- :py:const:`LI_BLOCK`: The contents of list items contain block
elements (e.g. paragraphs).
.. py:method:: listitem(content, flags=0)
``flags`` can contain the following flags:
- :py:const:`LIST_ORDERED`: An ordered list.
- :py:const:`LI_BLOCK`: The contents of list items contain block
elements (e.g. paragraphs).
.. py:method:: listitem(content, is_ordered, is_block)
.. py:method:: paragraph(content)
.. py:method:: table(content)
Depends on :py:const:`EXT_TABLES`.
Depends on the tables extension.
.. py:method:: table_header(content)
Depends on :py:const:`EXT_TABLES`.
Depends on the tables extension.
.. py:method:: table_body(content)
Depends on :py:const:`EXT_TABLES`.
Depends on the tables extension.
.. py:method:: table_row(content)
Depends on :py:const:`EXT_TABLES`.
Depends on the tables extension.
.. py:method:: table_cell(content, flags=0)
.. py:method:: table_cell(content, align, is_header)
Depends on :py:const:`EXT_TABLES`.
Depends on the tables extension.
``flags`` can contain the following flags:
- :py:const:`TABLE_ALIGNMASK`: Alignment of the table cell.
- :py:const:`TABLE_HEADER`: Table cell is located in the table header.
``TABLE_ALIGNMASK`` can be used to check what the alignment of the
cell is. Here's an example:
.. code:: python
align_bit = flags & misaka.TABLE_ALIGNMASK
if align_bit == misaka.TABLE_ALIGN_CENTER:
align = 'center'
elif align_bit == misaka.TABLE_ALIGN_LEFT:
align = 'left'
elif align_bit == misaka.TABLE_ALIGN_RIGHT:
align = 'right'
else:
align = ''
``align`` can be empty, ``center``, ``left`` or ``right``.
.. py:method:: footnotes(content)
Depends on :py:const:`EXT_FOOTNOTES`.
Depends on the footnotes extension.
.. py:method:: footnote_def(content, num)
Depends on :py:const:`EXT_FOOTNOTES`.
Depends on the footnotes extension.
.. py:method:: footnote_ref(num)
Depends on :py:const:`EXT_FOOTNOTES`.
Depends on the footnotes extension.
.. py:method:: blockhtml(text)
.. py:method:: autolink(link, type)
.. py:method:: autolink(link, is_email)
Depends on :py:const:`EXT_AUTOLINK`.
``type`` can be :py:const:`AUTOLINK_NORMAL` or
:py:const:`AUTOLINK_EMAIL`.
Depends on the autolink extension.
.. py:method:: codespan(text)
@ -281,15 +292,15 @@ Classes
.. py:method:: underline(content)
Depends on :py:const:`EXT_UNDERLINE`.
Depends on the underline extension.
.. py:method:: highlight(content)
Depends on :py:const:`EXT_HIGHLIGHT`.
Depends on the highlight extension.
.. py:method:: quote(content)
Depends on :py:const:`EXT_QUOTE`.
Depends on the quote extension.
.. py:method:: image(link, title='', alt='')
@ -301,15 +312,15 @@ Classes
.. py:method:: strikethrough(content)
Depends on :py:const:`EXT_STRIKETHROUGH`.
Depends on the strikethrough extension.
.. py:method:: superscript(content)
Depends on :py:const:`EXT_SUPERSCRIPT`.
Depends on the superscript extension.
.. py:method:: math(text, displaymode)
Depends on :py:const:`EXT_MATH`.
Depends on the math extension.
``displaymode`` can be ``0`` or ``1``. This is how
:py:class:`HtmlRenderer` handles it:
@ -330,23 +341,3 @@ Classes
.. py:method:: doc_header(inline_render)
.. py:method:: doc_footer(inline_render)
.. autoclass:: HtmlRenderer
:members:
.. autoclass:: HtmlTocRenderer
:members:
.. autoclass:: Markdown
:members:
Functions
^^^^^^^^^
.. autofunction:: html
.. autofunction:: smartypants

16
misaka/api.py
View File

@ -61,6 +61,14 @@ MAX_NESTING = 16
def html(text, extensions=0, render_flags=0):
"""
Convert markdown text to HTML.
``extensions`` can be a list or tuple of extensions (e.g.
``('fenced-code', 'footnotes', 'strikethrough')``) or an integer
(e.g. ``EXT_FENCED_CODE | EXT_FOOTNOTES | EXT_STRIKETHROUGH``).
``render_flags`` can be a list or tuple of flags (e.g.
``('skip-html', 'hard-wrap')``) or an integer
(e.g. ``HTML_SKIP_HTML | HTML_HARD_WRAP``).
"""
extensions = args_to_int(extension_map, extensions)
render_flags = args_to_int(html_flag_map, render_flags)
@ -116,6 +124,10 @@ def smartypants(text):
class Markdown(object):
"""
Parses markdown text and renders it using the given renderer.
``extensions`` can be a list or tuple of extensions (e.g.
``('fenced-code', 'footnotes', 'strikethrough')``) or an integer
(e.g. ``EXT_FENCED_CODE | EXT_FOOTNOTES | EXT_STRIKETHROUGH``).
"""
def __init__(self, renderer, extensions=0):
self.renderer = renderer
@ -166,6 +178,10 @@ class HtmlRenderer(BaseRenderer):
"""
A wrapper for the HTML renderer that's included in Hoedown.
``render_flags`` can be a list or tuple of flags (e.g.
``('skip-html', 'hard-wrap')``) or an integer
(e.g. ``HTML_SKIP_HTML | HTML_HARD_WRAP``).
``nesting_level`` limits what's included in the table of contents.
The default value is 0, no headers.