diff options
| author | Waylan Limberg <waylan@gmail.com> | 2012-03-01 11:14:41 -0500 |
|---|---|---|
| committer | Waylan Limberg <waylan@gmail.com> | 2012-03-01 11:14:41 -0500 |
| commit | dc49e92bad4f2534a6080849365186fe62343b8f (patch) | |
| tree | 532107f56a53bc7129575898f290a5715c771057 | |
| parent | 61ebd008e9ade549fcc3e934f4267472211c4b60 (diff) | |
| download | markdown-dc49e92bad4f2534a6080849365186fe62343b8f.tar.gz markdown-dc49e92bad4f2534a6080849365186fe62343b8f.tar.bz2 markdown-dc49e92bad4f2534a6080849365186fe62343b8f.zip | |
Refactored Docs to use Sphinx styled template.
This is not a full Sphinx implementation. Just a limited implementation
which converts our markdown source filed to work with the default css for
Sphinx so it looks like Pythons docs.
30 files changed, 975 insertions, 48 deletions
diff --git a/docs/_template.html b/docs/_template.html index 58fde35..fa26d43 100644 --- a/docs/_template.html +++ b/docs/_template.html @@ -2,17 +2,80 @@ <html> <head> <meta charset=utf-8> -<title>%(title)s</title> -<link rel=stylesheet href=style.css> +<title>%(page_title)s</title> +<link rel="stylesheet" href="%(base)sdefault.css" type="text.css"> </head> <body> -<div id="nav"> -<p><a href="/">Index</a></p> -%(toc)s -</div> -<div id="content"> + +<div class="related"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="siteindex.html" title="General Index">index</a></li> + <li class="right"> + <a href="%(next_url)s" title="%(next_title)s" + accesskey="N">next</a> |</li> + <li class="right"> + <a href="%(prev_url)s" title="%(prev_title)s" + accesskey="P">previous</a> |</li> + <li><img src="%(base)spy.png" alt="" + style="vertical-align: middle; margin-top: -1px"/></li> + <li><a href="%(base)sindex.html">Python Markdown v%(version)s documentation</a> »</li> + %(crumb)s + </ul> +</div> <!-- .related --> + +<div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body"> %(body)s -</div> -<p id="foot">© 2010 Python Markdown Project<p> + </div> <!-- .body --> + </div> <!-- .bodywrapper --> + </div> <!-- .documentwrapper --> + + <div class="sphinxsidebar"> + <div class="sphinxsidebarwrapper"> + <h3>Table Of Contents</h3> + %(toc)s + + <h4>Previous topic</h4> + <p class="topless"><a href="%(prev_url)s" + title="previous chapter">%(prev_title)s</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="%(next_url)s" + title="next chapter">%(next_title)s</a></p> + <h3>This Page</h3> + <ul class="this-page-menu"> + <li><a href="https://github.com/waylan/Python-Markdown/issues" + >Report a Bug</a></li> + <li><a href="%(source)s" + rel="nofollow">Show Source</a></li> + </ul> + </div> <!-- .sphinxsidebarwrapper --> + </div> <!-- .sphinxsidebar --> + + <div class="clearer"></div> +</div> <!-- .document --> + +<div class="related"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="siteindex.html" title="General Index">index</a></li> + <li class="right"> + <a href="%(next_url)s" title="%(next_title)s" + accesskey="N">next</a> |</li> + <li class="right"> + <a href="%(prev_url)s" title="%(prev_title)s" + accesskey="P">previous</a> |</li> + <li><img src="%(base)spy.png" alt="" + style="vertical-align: middle; margin-top: -1px"/></li> + <li><a href="%(base)sindex.html">Python Markdown v%(version)s documentation</a> »</li> + %(crumb)s + </ul> +</div> <!-- .related --> + +<div class="footer">© 2010-2012 Python Markdown Project</div> </body> </html> diff --git a/docs/basic.css b/docs/basic.css new file mode 100644 index 0000000..2b47622 --- /dev/null +++ b/docs/basic.css @@ -0,0 +1,438 @@ +/** + * Sphinx stylesheet -- basic theme + * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + */ + +/* -- main layout ----------------------------------------------------------- */ + +div.clearer { + clear: both; +} + +/* -- relbar ---------------------------------------------------------------- */ + +div.related { + width: 100%; + font-size: 90%; +} + +div.related h3 { + display: none; +} + +div.related ul { + margin: 0; + padding: 0 0 0 10px; + list-style: none; +} + +div.related li { + display: inline; +} + +div.related li.right { + float: right; + margin-right: 5px; +} + +/* -- sidebar --------------------------------------------------------------- */ + +div.sphinxsidebarwrapper { + padding: 10px 5px 0 10px; +} + +div.sphinxsidebar { + float: left; + width: 230px; + margin-left: -100%; + font-size: 90%; +} + +div.sphinxsidebar ul { + list-style: none; +} + +div.sphinxsidebar ul ul, +div.sphinxsidebar ul.want-points { + margin-left: 20px; + list-style: square; +} + +div.sphinxsidebar ul ul { + margin-top: 0; + margin-bottom: 0; +} + +div.sphinxsidebar form { + margin-top: 10px; +} + +div.sphinxsidebar input { + border: 1px solid #98dbcc; + font-family: sans-serif; + font-size: 1em; +} + +img { + border: 0; +} + +/* -- search page ----------------------------------------------------------- */ + +ul.search { + margin: 10px 0 0 20px; + padding: 0; +} + +ul.search li { + padding: 5px 0 5px 20px; + background-image: url(file.png); + background-repeat: no-repeat; + background-position: 0 7px; +} + +ul.search li a { + font-weight: bold; +} + +ul.search li div.context { + color: #888; + margin: 2px 0 0 30px; + text-align: left; +} + +ul.keywordmatches li.goodmatch a { + font-weight: bold; +} + +/* -- index page ------------------------------------------------------------ */ + +table.contentstable { + width: 90%; +} + +table.contentstable p.biglink { + line-height: 150%; +} + +a.biglink { + font-size: 1.3em; +} + +span.linkdescr { + font-style: italic; + padding-top: 5px; + font-size: 90%; +} + +/* -- general index --------------------------------------------------------- */ + +table.indextable td { + text-align: left; + vertical-align: top; +} + +table.indextable dl, table.indextable dd { + margin-top: 0; + margin-bottom: 0; +} + +table.indextable tr.pcap { + height: 10px; +} + +table.indextable tr.cap { + margin-top: 10px; + background-color: #f2f2f2; +} + +img.toggler { + margin-right: 3px; + margin-top: 3px; + cursor: pointer; +} + +/* -- general body styles --------------------------------------------------- */ + +a.headerlink { + visibility: hidden; +} + +h1:hover > a.headerlink, +h2:hover > a.headerlink, +h3:hover > a.headerlink, +h4:hover > a.headerlink, +h5:hover > a.headerlink, +h6:hover > a.headerlink, +dt:hover > a.headerlink { + visibility: visible; +} + +div.body p.caption { + text-align: inherit; +} + +div.body td { + text-align: left; +} + +.field-list ul { + padding-left: 1em; +} + +.first { + margin-top: 0 !important; +} + +p.rubric { + margin-top: 30px; + font-weight: bold; +} + +/* -- sidebars -------------------------------------------------------------- */ + +div.sidebar { + margin: 0 0 0.5em 1em; + border: 1px solid #ddb; + padding: 7px 7px 0 7px; + background-color: #ffe; + width: 40%; + float: right; +} + +p.sidebar-title { + font-weight: bold; +} + +/* -- topics ---------------------------------------------------------------- */ + +div.topic { + border: 1px solid #ccc; + padding: 7px 7px 0 7px; + margin: 10px 0 10px 0; +} + +p.topic-title { + font-size: 1.1em; + font-weight: bold; + margin-top: 10px; +} + +/* -- admonitions ----------------------------------------------------------- */ + +div.admonition { + margin-top: 10px; + margin-bottom: 10px; + padding: 7px; +} + +div.admonition dt { + font-weight: bold; +} + +div.admonition dl { + margin-bottom: 0; +} + +p.admonition-title { + margin: 0px 10px 5px 0px; + font-weight: bold; +} + +div.body p.centered { + text-align: center; + margin-top: 25px; +} + +/* -- tables ---------------------------------------------------------------- */ + +table.docutils { + border: 0 solid #dce; + border-collapse: collapse; +} + +table.docutils td, table.docutils th { + padding: 2px 5px 2px 5px; + border-left: 0; + background-color: #eef; +} + +table.docutils td p.last, table.docutils th p.last { + margin-bottom: 0; +} + +table.field-list td, table.field-list th { + border: 0 !important; +} + +table.footnote td, table.footnote th { + border: 0 !important; +} + +table.docutils th { + border-top: 1px solid #cac; + background-color: #ede; +} + +th { + text-align: left; + padding-right: 5px; +} + +th.head { + text-align: center; +} + +/* -- other body styles ----------------------------------------------------- */ + +dl { + margin-bottom: 15px; +} + +dd p { + margin-top: 0px; +} + +dd ul, dd table { + margin-bottom: 10px; +} + +dd { + margin-top: 3px; + margin-bottom: 10px; + margin-left: 30px; +} + +dt:target, .highlight { + background-color: #fbe54e; +} + +dl.glossary dt { + font-weight: bold; + font-size: 1.1em; +} + +.field-list ul { + margin: 0; + padding-left: 1em; +} + +.field-list p { + margin: 0; +} + +.refcount { + color: #060; +} + +.optional { + font-size: 1.3em; +} + +.versionmodified { + font-style: italic; +} + +p.deprecated { + background-color: #ffe4e4; + border: 1px solid #f66; + padding: 7px +} + +.system-message { + background-color: #fda; + padding: 5px; + border: 3px solid red; +} + +.footnote:target { + background-color: #ffa; +} + +.impl-detail { + margin-top: 10px; + margin-bottom: 10px; + padding: 7px; + border: 1px solid #ccc; +} + +.impl-detail .compound-first { + margin-top: 0; +} + +.impl-detail .compound-last { + margin-bottom: 0; +} + +/* -- code displays --------------------------------------------------------- */ + +pre { + overflow: auto; + overflow-y: hidden; +} + +td.linenos pre { + padding: 5px 0px; + border: 0; + background-color: transparent; + color: #aaa; +} + +table.highlighttable { + margin-left: 0.5em; +} + +table.highlighttable td { + padding: 0 0.5em 0 0.5em; +} + +tt.descname { + background-color: transparent; + font-weight: bold; + font-size: 1.2em; +} + +tt.descclassname { + background-color: transparent; +} + +tt.xref, a tt { + background-color: transparent; + font-weight: bold; +} + +h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt { + background-color: transparent; +} + +/* -- math display ---------------------------------------------------------- */ + +img.math { + vertical-align: middle; +} + +div.body div.math p { + text-align: center; +} + +span.eqno { + float: right; +} + +/* -- printout stylesheet --------------------------------------------------- */ + +@media print { + div.document, + div.documentwrapper, + div.bodywrapper { + margin: 0 !important; + width: 100%; + } + + div.sphinxsidebar, + div.related, + div.footer, + #top-link { + display: none; + } +} diff --git a/docs/command_line.md b/docs/command_line.md index b999ca6..c597c52 100644 --- a/docs/command_line.md +++ b/docs/command_line.md @@ -1,3 +1,10 @@ +title: Command Line +prev_title: Library Reference +prev_url: using_as_module.html +next_title: Extensions +next_url: extensions/index.html + + Using Python-Markdown on the Command Line ========================================= diff --git a/docs/default.css b/docs/default.css new file mode 100644 index 0000000..7833719 --- /dev/null +++ b/docs/default.css @@ -0,0 +1,261 @@ +/* + * default.css_t + * ~~~~~~~~~~~~~ + * + * Sphinx stylesheet -- default theme. + * + * :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS. + * :license: BSD, see LICENSE for details. + * + */ + +@import url("basic.css"); + +/* -- page layout ----------------------------------------------------------- */ + +body { + font-family: sans-serif; + font-size: 100%; + background-color: #11303d; + color: #000; + margin: 0; + padding: 0; +} + +div.document { + background-color: #1c4e63; +} + +div.documentwrapper { + float: left; + width: 100%; +} + +div.bodywrapper { + margin: 0 0 0 230px; +} + +div.body { + background-color: #ffffff; + color: #000000; + padding: 0 20px 30px 20px; +} + +div.footer { + color: #ffffff; + width: 100%; + padding: 9px 0 9px 0; + text-align: center; + font-size: 75%; +} + +div.footer a { + color: #ffffff; + text-decoration: underline; +} + +div.related { + background-color: #133f52; + line-height: 30px; + color: #ffffff; +} + +div.related a { + color: #ffffff; +} + +div.sphinxsidebar { +} + +div.sphinxsidebar h3 { + font-family: 'Trebuchet MS', sans-serif; + color: #ffffff; + font-size: 1.4em; + font-weight: normal; + margin: 0; + padding: 0; +} + +div.sphinxsidebar h3 a { + color: #ffffff; +} + +div.sphinxsidebar h4 { + font-family: 'Trebuchet MS', sans-serif; + color: #ffffff; + font-size: 1.3em; + font-weight: normal; + margin: 5px 0 0 0; + padding: 0; +} + +div.sphinxsidebar p { + color: #ffffff; +} + +div.sphinxsidebar p.topless { + margin: 5px 10px 10px 10px; +} + +div.sphinxsidebar ul { + margin: 10px; + padding: 0; + color: #ffffff; +} + +div.sphinxsidebar a { + color: #98dbcc; +} + +div.sphinxsidebar input { + border: 1px solid #98dbcc; + font-family: sans-serif; + font-size: 1em; +} + + +/* for collapsible sidebar */ +div#sidebarbutton { + background-color: #3c6e83; +} + + +/* -- hyperlink styles ------------------------------------------------------ */ + +a { + color: #355f7c; + text-decoration: none; +} + +a:visited { + color: #355f7c; + text-decoration: none; +} + +a:hover { + text-decoration: underline; +} + + + +/* -- body styles ----------------------------------------------------------- */ + +div.body h1, +div.body h2, +div.body h3, +div.body h4, +div.body h5, +div.body h6 { + font-family: 'Trebuchet MS', sans-serif; + background-color: #f2f2f2; + font-weight: normal; + color: #20435c; + border-bottom: 1px solid #ccc; + margin: 20px -20px 10px -20px; + padding: 3px 0 3px 10px; +} + +div.body h1 { margin-top: 0; font-size: 200%; } +div.body h2 { font-size: 160%; } +div.body h3 { font-size: 140%; } +div.body h4 { font-size: 120%; } +div.body h5 { font-size: 110%; } +div.body h6 { font-size: 100%; } + +a.headerlink { + color: #c60f0f; + font-size: 0.8em; + padding: 0 4px 0 4px; + text-decoration: none; +} + +a.headerlink:hover { + background-color: #c60f0f; + color: white; +} + +div.body p, div.body dd, div.body li { + text-align: justify; + line-height: 130%; +} + +div.admonition p.admonition-title + p { + display: inline; +} + +div.admonition p { + margin-bottom: 5px; +} + +div.admonition pre { + margin-bottom: 5px; +} + +div.admonition ul, div.admonition ol { + margin-bottom: 5px; +} + +div.note { + background-color: #eee; + border: 1px solid #ccc; +} + +div.seealso { + background-color: #ffc; + border: 1px solid #ff6; +} + +div.topic { + background-color: #eee; +} + +div.warning { + background-color: #ffe4e4; + border: 1px solid #f66; +} + +p.admonition-title { + display: inline; +} + +p.admonition-title:after { + content: ":"; +} + +pre { + padding: 5px; + background-color: #eeffcc; + color: #333333; + line-height: 120%; + border: 1px solid #ac9; + border-left: none; + border-right: none; +} + +tt { + background-color: #ecf0f3; + padding: 0 1px 0 1px; + font-size: 0.95em; +} + +th { + background-color: #ede; +} + +.warning tt { + background: #efc2c2; +} + +.note tt { + background: #d6d6d6; +} + +.viewcode-back { + font-family: sans-serif; +} + +div.viewcode-block:target { + background-color: #f4debf; + border-top: 1px solid #ac9; + border-bottom: 1px solid #ac9; +}
\ No newline at end of file diff --git a/docs/extensions/abbreviations.md b/docs/extensions/abbreviations.md index fa54d3c..994d8dc 100644 --- a/docs/extensions/abbreviations.md +++ b/docs/extensions/abbreviations.md @@ -1,3 +1,9 @@ +title: Abbreviation Extension +prev_title: Extra Extension +prev_url: extra.html +next_title: Attribute List Extension +next_url: attr_list.html + Abbreviations ------------- diff --git a/docs/extensions/attr_list.md b/docs/extensions/attr_list.md index 6bfe07b..11c6a28 100644 --- a/docs/extensions/attr_list.md +++ b/docs/extensions/attr_list.md @@ -1,3 +1,9 @@ +title: Attribute List Extension +prev_title: Abbreviation Extension +prev_url: abbreviations.html +next_title: Definition List Extension +next_url: definition_lists.html + Attribute Lists =============== diff --git a/docs/extensions/code_hilite.md b/docs/extensions/code_hilite.md index 74282f6..aa0fe57 100644 --- a/docs/extensions/code_hilite.md +++ b/docs/extensions/code_hilite.md @@ -1,3 +1,9 @@ +title: CodeHilite Extension +prev_title: Smart Strong Extension +prev_url: smart_strong.html +next_title: HTML Tidy Extension +next_url: html_tidy.html + CodeHilite ========== diff --git a/docs/extensions/definition_lists.md b/docs/extensions/definition_lists.md index 983070d..a76be5c 100644 --- a/docs/extensions/definition_lists.md +++ b/docs/extensions/definition_lists.md @@ -1,3 +1,9 @@ +title: Definition List Extension +prev_title: Attribute List Extension +prev_url: attr_list.html +next_title: Fenced Code Block Extension +next_url: fenced_code_blocks.html + Definition Lists ---------------- diff --git a/docs/extensions/extra.md b/docs/extensions/extra.md index 9bb94c2..998a200 100644 --- a/docs/extensions/extra.md +++ b/docs/extensions/extra.md @@ -1,3 +1,9 @@ +title: Extra Extension +prev_title: Extensions +prev_url: index.html +next_title: Abreviation Extension +next_url: abbreviations.html + Python-Markdown Extra ===================== diff --git a/docs/extensions/fenced_code_blocks.md b/docs/extensions/fenced_code_blocks.md index 6b1ba76..0aa0d34 100644 --- a/docs/extensions/fenced_code_blocks.md +++ b/docs/extensions/fenced_code_blocks.md @@ -1,3 +1,9 @@ +title: Fenced Code Block Extension +prev_title: Definition List Extension +prev_url: definition_lists.html +next_title: Footnotes Extension +next_url: footnotes.html + Fenced Code Blocks ================== diff --git a/docs/extensions/footnotes.md b/docs/extensions/footnotes.md index 7188f44..1d6593c 100644 --- a/docs/extensions/footnotes.md +++ b/docs/extensions/footnotes.md @@ -1,3 +1,9 @@ +title: Footnotes Extension +prev_title: Fenced Code Block Extension +prev_url: fenced_code_blocks.html +next_title: Tables Extension +next_url: tables.html + Footnotes ========= diff --git a/docs/extensions/header_id.md b/docs/extensions/header_id.md index 90a6673..255d35c 100644 --- a/docs/extensions/header_id.md +++ b/docs/extensions/header_id.md @@ -1,3 +1,9 @@ +title: HeaderId Extension +prev_title: HTML Tidy Extension +prev_url: html_tidy.html +next_title: Meta-Data Extension +next_url: meta_data.html + HeaderId ======== diff --git a/docs/extensions/html_tidy.md b/docs/extensions/html_tidy.md index 52f991f..db807f7 100644 --- a/docs/extensions/html_tidy.md +++ b/docs/extensions/html_tidy.md @@ -1,3 +1,9 @@ +title: HTML Tidy Extension +prev_title: CodeHilite Extension +prev_url: code_hilite.html +next_title: HeaderId Extension +next_url: header_id.html + HTML Tidy ========= diff --git a/docs/extensions/index.md b/docs/extensions/index.md index 82f00a4..b09b2c2 100644 --- a/docs/extensions/index.md +++ b/docs/extensions/index.md @@ -1,3 +1,10 @@ +title: Extensions +prev_title: Command Line +prev_url: ../command_line.html +next_title: Extra Extension +next_url: extra.html + + Available Extensions ==================== @@ -20,7 +27,7 @@ See [Using Python-Markdown on the Command Line](../command_line.html) or use the Officially Supported Extensions ------------------------------- -The extensions lists below are included with (at least) the most recent release +The extensions listed below are included with (at least) the most recent release and are officially supported by Python-Markdown. Any documentation is maintained here and all bug reports should be made to the project. If you have a typical install of Python-Markdown, these extensions are already diff --git a/docs/extensions/meta_data.md b/docs/extensions/meta_data.md index 3342722..8c156c9 100644 --- a/docs/extensions/meta_data.md +++ b/docs/extensions/meta_data.md @@ -1,3 +1,9 @@ +title: Meta-Data Extension +prev_title: HeaderId Extension +prev_url: header_id.html +next_title: New Line to Break Extension +next_url: nl2br.html + Meta-Data ========= diff --git a/docs/extensions/nl2br.md b/docs/extensions/nl2br.md index 27030f7..affd8ee 100644 --- a/docs/extensions/nl2br.md +++ b/docs/extensions/nl2br.md @@ -1,3 +1,9 @@ +title: New Line to Break Extension +prev_title: Meta-Data Extension +prev_url: meta_data.html +next_title: RSS Extension +next_url: rss.html + NL2BR Extension =============== diff --git a/docs/extensions/rss.md b/docs/extensions/rss.md index f2ecf0c..67e6d96 100644 --- a/docs/extensions/rss.md +++ b/docs/extensions/rss.md @@ -1,3 +1,9 @@ +title: RSS Extension +prev_title: New Line to Break Extension +prev_url: nl2br.html +next_title: Sane Lists Extension +next_url: sane_lists.html + RSS === diff --git a/docs/extensions/sane_lists.md b/docs/extensions/sane_lists.md index b1c1d06..c108ad8 100644 --- a/docs/extensions/sane_lists.md +++ b/docs/extensions/sane_lists.md @@ -1,3 +1,9 @@ +title: Sane Lists Extension +prev_title: RSS Extension +prev_url: rss.html +next_title: Table of Contents Extension +next_url: toc.html + Sane Lists ---------- diff --git a/docs/extensions/smart_strong.md b/docs/extensions/smart_strong.md index 6ccb1b7..22468d6 100644 --- a/docs/extensions/smart_strong.md +++ b/docs/extensions/smart_strong.md @@ -1,3 +1,9 @@ +title: Smart Strong Extension +prev_title: Tables Extension +prev_url: tables.html +next_title: CodeHilite Extension +next_url: code_hilite.html + Smart_Strong ------------ diff --git a/docs/extensions/tables.md b/docs/extensions/tables.md index 63d6849..e37a752 100644 --- a/docs/extensions/tables.md +++ b/docs/extensions/tables.md @@ -1,3 +1,9 @@ +title: Table Extension +prev_title: Footnotes Extension +prev_url: footnotes.html +next_title: Smart Strong Extension +next_url: smart_strong.html + Tables ---------------- diff --git a/docs/extensions/toc.md b/docs/extensions/toc.md index 032c25c..632294b 100644 --- a/docs/extensions/toc.md +++ b/docs/extensions/toc.md @@ -1,3 +1,9 @@ +title: Table of Contents Extension +prev_title: Sane Lists Extension +prev_url: sane_lists.html +next_title: Wikilinks Extension +next_url: wikilinks.html + Table of Contents ================= diff --git a/docs/extensions/wikilinks.md b/docs/extensions/wikilinks.md index c54f6d4..22baf9f 100644 --- a/docs/extensions/wikilinks.md +++ b/docs/extensions/wikilinks.md @@ -1,3 +1,9 @@ +title: Wikilinks Extension +prev_title: Table of Contents Extension +prev_url: toc.html +next_title: Extension API +next_url: ../writing_extensions.html + WikiLinks ========= diff --git a/docs/index.md b/docs/index.md index 55d5be0..1c6ca5a 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,3 +1,6 @@ +next_url: install.html +next_title: Installation + Python-Markdown =============== @@ -16,37 +19,37 @@ Features In addition to the basic markdown syntax, Python-Markdown supports the following features: -* International Input +* __International Input__ Python-Markdown will accept input in any language supported by Unicode including bi-directional text. In fact the test suite includes documents written in Russian and Arabic. -* Middle-Word Emphasis +* __Middle-Word Emphasis__ Python-Markdown defaults to ignoring middle-word emphasis. In other words, `some_long_filename.txt` will not become `some<em>long</em>filename.txt`. This can be switched off if desired. See the [Library Reference](using_as_module.html) for details. -* Extensions +* __Extensions__ Various [extensions](extensions/) are provided (including [extra](extensions/extra.html)) to expand the base syntax. Additionally, a public [Extension API](writing_extensions.html) is available to write your own extensions. -* Output Formats +* __Output Formats__ Python-Markdown can output documents in HTML4, XHTML and HTML5. -* "Safe Mode" +* __"Safe Mode"__ When using Python-Markdown to parse input from untrusted users on the web, the handling of raw HTML can be controlled in various ways to prevent harmful code from being injected into your site. -* Command Line Interface +* __Command Line Interface__ In addition to being a Python Library, a [command line script](command_line.html) is available for your convenience. diff --git a/docs/install.md b/docs/install.md index c64d144..cc2a10d 100644 --- a/docs/install.md +++ b/docs/install.md @@ -1,3 +1,9 @@ +title: Installation +prev_title: Summary +prev_url: index.html +next_title: Library Reference +next_url: using_as_module.html + Installing Python-Markdown ========================== diff --git a/docs/py.png b/docs/py.png Binary files differnew file mode 100644 index 0000000..93e4a02 --- /dev/null +++ b/docs/py.png diff --git a/docs/style.css b/docs/style.css deleted file mode 100644 index 33e2c70..0000000 --- a/docs/style.css +++ /dev/null @@ -1,2 +0,0 @@ - -.nav { float:right; margin:1em;} diff --git a/docs/test_suite.md b/docs/test_suite.md index 5cad250..c1034b6 100644 --- a/docs/test_suite.md +++ b/docs/test_suite.md @@ -1,3 +1,7 @@ +title: Test Suite +prev_title: Extension API +prev_url: writing_extensions.html + # Test Suite Python-Markdown comes with a test suite which uses the [Nose][] testing diff --git a/docs/using_as_module.md b/docs/using_as_module.md index f460921..72c4965 100644 --- a/docs/using_as_module.md +++ b/docs/using_as_module.md @@ -1,3 +1,10 @@ +title: Library Reference +prev_title: Installation +prev_url: install.html +next_title: Command Line +next_url: command_line.html + + Using Markdown as a Python Library ================================== @@ -26,7 +33,7 @@ of the `markdown.Markdown` class and pass multiple documents through it. The following options are available on the `markdown.markdown` function: -* `text` (required): The source text string. +* __`text`__ (required): The source text string. Note that Python-Markdown expects **Unicode** as input (although a simple ASCII string may work) and returns output as Unicode. @@ -45,7 +52,7 @@ The following options are available on the `markdown.markdown` function: ) output_file.write(html) -* `extensions`: A list of extensions. +* __`extensions`__: A list of extensions. Python-Markdown provides an API for third parties to write extensions to the parser adding their own additions or changes to the syntax. A few @@ -60,7 +67,7 @@ The following options are available on the `markdown.markdown` function: `extensions=['extra']` will first look for the module `markdown.extensions.extra`, then a module named `mdx_extra`. -* `extension-configs`: A dictionary of configuration settings for extensions. +* __`extension-configs`__: A dictionary of configuration settings for extensions. The dictionary must be of the following format: @@ -77,7 +84,7 @@ The following options are available on the `markdown.markdown` function: See the documentation specific to the extension you are using for help in specifying configuration settings for that extension. -* `output_format`: Format of output. +* __`output_format`__: Format of output. Supported formats are: @@ -93,7 +100,7 @@ The following options are available on the `markdown.markdown` function: if it makes sense at that time. The values can either be lowercase or uppercase. -* `safe_mode`: Disallow raw html. +* __`safe_mode`__: Disallow raw html. If you are using Markdown on a web system which will transform text provided by untrusted users, you may want to use the "safe_mode" @@ -130,16 +137,16 @@ The following options are available on the `markdown.markdown` function: could allow someone to inject javascript (i.e., `{@onclick=alert(1)}`). You may also want to set `enable_attributes=False` when using "safe_mode". -* `html_replacement_text`: Text used when safe_mode is set to `replace`. +* __`html_replacement_text`__: Text used when safe_mode is set to `replace`. Defaults to `[HTML_REMOVED]`. -* `tab_length`: Length of tabs in the source. Default: 4 +* __`tab_length`__: Length of tabs in the source. Default: 4 -* `enable_attributes`: Enable the conversion of attributes. Default: True +* __`enable_attributes`__: Enable the conversion of attributes. Default: True -* `smart_emphasis`: Treat `_connected_words_` intelligently Default: True +* __`smart_emphasis`__: Treat `_connected_words_` intelligently Default: True -* `lazy_ol`: Ignore number of first item of ordered lists. Default: True +* __`lazy_ol`__: Ignore number of first item of ordered lists. Default: True Given the following list: @@ -165,7 +172,7 @@ With a few exceptions, `markdown.markdownFromFile` accepts the same options as `markdown.markdown`. It does **not** accept a `text` (or Unicode) string. Instead, it accepts the following required options: -* `input` (required): The source text file. +* __`input`__ (required): The source text file. `input` may be set to one of three options: @@ -173,7 +180,7 @@ Instead, it accepts the following required options: * a readable file-like object, * or `None` (default) which will read from `stdin`. -* `output`: The target which output is written to. +* __`output`__: The target which output is written to. `output` may be set to one of three options: @@ -181,7 +188,7 @@ Instead, it accepts the following required options: * a writable file-like object, * or `None` (default) which will write to `stdout`. -* `encoding`: The encoding of the source text file. Defaults to +* __`encoding`__: The encoding of the source text file. Defaults to "utf-8". The same encoding will always be used for input and output. The 'xmlcharrefreplace' error handler is used when encoding the output. diff --git a/docs/writing_extensions.md b/docs/writing_extensions.md index 8a6a073..1e40019 100644 --- a/docs/writing_extensions.md +++ b/docs/writing_extensions.md @@ -1,3 +1,9 @@ +title: Extensions API +prev_title: Wikilinks Extension +prev_url: extensions/wikilinks.html +next_title: Test Suite +next_url: test_suite.html + Writing Extensions for Python-Markdown ====================================== @@ -73,20 +73,44 @@ class build_docs(Command): for file in files: if not file.startswith('_'): path = os.path.join(root, file) - yield (path, self._get_page_title(path)) - - def _get_page_title(self, path): - """ Get page title from file name (and path). """ - root, ext = os.path.splitext(path) - path, name = os.path.split(root) - parts = path.split(os.sep) + yield path + + def _get_context(self, src, path): + """ Build and return context to pass to template. """ + # set defaults + c = { + 'title' : '', + 'prev_url' : '', + 'prev_title' : '', + 'next_url' : '', + 'next_title' : '', + 'crumb' : '', + 'version' : version, + } + c['body'] = self.md.convert(src) + c['toc'] = self.md.toc + for k, v in self.md.Meta.items(): + c[k] = ' '.join(v) + self.md.reset() + # Manipulate path + path = path.lstrip(os.path.join(self.build_base, 'docs/')) + dir, file = os.path.split(path) + name, ext = os.path.splitext(file) + parts = [x for x in dir.split(os.sep) if x] + c['source'] = '%s.txt' % name + c['base'] = '../'*len(parts) + # Build page title parts = [x.replace('_', ' ').capitalize() for x in parts[1:]] if name.lower() != 'index': parts.append(name.replace('_', ' ').capitalize()) if parts: - return ' | '.join(parts) + ' — Python Markdown' + c['page_title'] = ' | '.join(parts) + ' — Python Markdown' else: - return 'Python Markdown' + c['page_title'] = 'Python Markdown' + # Build crumb trail + if c['title']: + c['crumb'] = '<li><a href="%s">%s</a> »</li>' % (file, c['title']) + return c def run(self): # Before importing markdown, tweak sys.path to import from the @@ -99,10 +123,16 @@ class build_docs(Command): print ('skipping build_docs: Markdown "import" failed!') else: template = codecs.open('docs/_template.html', encoding='utf-8').read() - md = markdown.Markdown(extensions=['extra', 'toc']) - for infile, title in self.docs: + self.md = markdown.Markdown(extensions=['extra', 'toc', 'meta']) + for infile in self.docs: outfile, ext = os.path.splitext(infile) if ext == '.md': + # Copy src to .txt file + srcfile = outfile + '.txt' + srcfile = change_root(self.build_base, srcfile) + self.mkpath(os.path.split(srcfile)[0]) + self.copy_file(infile, srcfile) + # Render html file outfile += '.html' outfile = change_root(self.build_base, outfile) self.mkpath(os.path.split(outfile)[0]) @@ -111,12 +141,7 @@ class build_docs(Command): print ('Converting %s -> %s' % (infile, outfile)) if not self.dry_run: src = codecs.open(infile, encoding='utf-8').read() - out = template % { - 'title': title, - 'body' : md.convert(src), - 'toc' : md.toc, - } - md.reset() + out = template % self._get_context(src, outfile) doc = open(outfile, 'wb') doc.write(out.encode('utf-8')) doc.close() |
