diff options
Diffstat (limited to 'dev-python/m2r/files/m2r.1')
| -rw-r--r-- | dev-python/m2r/files/m2r.1 | 515 |
1 files changed, 0 insertions, 515 deletions
diff --git a/dev-python/m2r/files/m2r.1 b/dev-python/m2r/files/m2r.1 deleted file mode 100644 index 1a6c10b48a90..000000000000 --- a/dev-python/m2r/files/m2r.1 +++ /dev/null @@ -1,515 +0,0 @@ -.\" Man page generated from reStructuredText. -. -.TH "M2R" "1" "Mar 30, 2017" "0.1.5" "M2R" -.SH NAME -m2r \- M2R Documentation -. -.nr rst2man-indent-level 0 -. -.de1 rstReportMargin -\\$1 \\n[an-margin] -level \\n[rst2man-indent-level] -level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] -- -\\n[rst2man-indent0] -\\n[rst2man-indent1] -\\n[rst2man-indent2] -.. -.de1 INDENT -.\" .rstReportMargin pre: -. RS \\$1 -. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] -. nr rst2man-indent-level +1 -.\" .rstReportMargin post: -.. -.de UNINDENT -. RE -.\" indent \\n[an-margin] -.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] -.nr rst2man-indent-level -1 -.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] -.in \\n[rst2man-indent\\n[rst2man-indent-level]]u -.. -\fI\%PyPI\fP\fI\%PyPI version\fP\fI\%Build Status\fP\fI\%codecov\fP -.sp -.ce ----- - -.ce 0 -.sp -.sp -M2R converts a markdown file including reST markups to a valid reST format. -.SH WHY ANOTHER CONVERTER? -.sp -I wanted to write sphinx document in markdown, since it\(aqs widely used now and -easy to write code blocks and lists. However, converters using pandoc or -recommonmark do not support many reST markups and sphinx extensions. For -example, reST\(aqs reference link like \fBsee \(garef\(ga_\fP (this is very convenient in -long document in which same link appears multiple times) will be converted to -a code block in HTML like \fBsee <code>ref</code>_\fP, which is not expected. -.SH FEATURES -.INDENT 0.0 -.IP \(bu 2 -Basic markdown and some extensions (see below) -.INDENT 2.0 -.IP \(bu 2 -inline/block\-level raw html -.IP \(bu 2 -fenced\-code block -.IP \(bu 2 -tables -.IP \(bu 2 -footnotes (\fB[^1]\fP) -.UNINDENT -.IP \(bu 2 -Inline\- and Block\-level reST markups -.INDENT 2.0 -.IP \(bu 2 -single\- and multi\-line directives (\fB\&.. directive::\fP) -.IP \(bu 2 -inline\-roles (\fB:code:\(gaprint(1)\(ga ...\fP) -.IP \(bu 2 -ref\-link (\fBsee \(garef\(ga_\fP) -.IP \(bu 2 -footnotes (\fB[#fn]_\fP) -.IP \(bu 2 -math extension inspired by \fI\%recommonmark\fP -.UNINDENT -.IP \(bu 2 -Sphinx extension -.INDENT 2.0 -.IP \(bu 2 -add markdown support for sphinx -.IP \(bu 2 -\fBmdinclude\fP directive to include markdown from md or reST files -.UNINDENT -.UNINDENT -.SH INSTALLATION -.sp -Python 2.7 or Python 3.3+ is required. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -pip install m2r -.ft P -.fi -.UNINDENT -.UNINDENT -.SH USAGE -.SS Command Line -.sp -\fBm2r\fP command converts markdown file to reST format. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -m2r your_document.md [your_document2.md ...] -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Then you will find \fByour_document.rst\fP in the same directory. -.SS Programmatic Use -.sp -Instantiate \fBM2R\fP class and call with markdown text. Then it will return converted text. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -from m2r import M2R -m2r = M2R() -rest = m2r(\(aq# Title\en\enSentence.\(aq) -print(rest) -# Title -# ===== -# -# Sentence. -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Or, use \fBparse_from_file\fP function to load markdown file and obtain converted text. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -from m2r import parse_from_file -output = parse_from_file(\(aqmarkdown_file.md\(aq) -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -This is an example of setup.py to write README in markdown, and publish it to PyPI as reST format. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -readme_file = os.path.join(os.path.dirname(os.path.abspath(__file__)), \(aqREADME.md\(aq) -try: - from m2r import parse_from_file - readme = parse_from_file(readme_file) -except ImportError: - # m2r may not be installed in user environment - with open(readme_file) as f: - readme = f.read() -setup( - ..., - long_description=readme, - ..., -) -.ft P -.fi -.UNINDENT -.UNINDENT -.SS Sphinx Integration -.sp -In your conf.py, add the following lines. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -extensions = [ - ..., - \(aqm2r\(aq, -] - -# source_suffix = \(aq.rst\(aq -source_suffix = [\(aq.rst\(aq, \(aq.md\(aq] -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Write index.md and run \fBmake html\fP\&. -.sp -When \fBm2r\fP extension is enabled on sphinx and \fB\&.md\fP file is loaded, m2r -converts to reST and pass to sphinx, not making new \fB\&.rst\fP file. -.SS mdinclude directive -.sp -Like \fB\&.. include:: file\fP directive, \fB\&.. mdinclude:: file\fP directive inserts -markdown file at the line. -.sp -Note: do not use \fB\&.. include:: file\fP directive to include markdown file even if -in the markdown file, please use \fB\&.. mdinclude:: file\fP instead. -.SH RESTRICTIONS -.INDENT 0.0 -.IP \(bu 2 -In the reST\(aqs directives, markdown is not available. Please write in reST. -.IP \(bu 2 -Column alignment of tables is not supported. (reST does not support this feature) -.IP \(bu 2 -Heading with overline\-and\-underline is not supported. -.INDENT 2.0 -.IP \(bu 2 -Heading with underline is OK -.UNINDENT -.UNINDENT -.sp -If you find any bug or unexpected behaviour, please report it to -\fI\%Issues\fP\&. -.SH EXAMPLE -.sp -See \fI\%example document\fP and \fI\%its -source code\fP\&. -.sp -I\(aqm using m2r for writing user guide of \fI\%WDOM\fP\&. -So you can see it as another example. Its \fI\%HTML is -here\fP, and \fI\%its -source code is here\fP\&. -.SH ACKNOWLEDGEMENT -.sp -m2r is written as an extension of -\fI\%mistune\fP, which is highly extensible -pure\-python markdown parser. -Without the mistune, I couldn\(aqt write this. Thank you! -.SH LICENCE -.sp -\fI\%MIT\fP -.SH CONTENTS -.SS Example -.sp -This page is written in mixed markdown and reST. -Source code is \fI\%here\fP\&. -.SS Basic Markups (inline) -.sp -A \fBstrong\fP, \fIemphasis\fP, , \fBcode with single\-backtick\fP, -\fBcode with two\-backticks\fP, , -\fBreST\(aqs code role\fP, and delete. -.SS Link -.sp -Auto link to \fI\%http://example.com/\fP\&. -.sp -Link to \fI\%example.com\fP in markdown. -.sp -Link to \fI\%example.com\fP in reST. -.sp -Link to \fI\%example\fP in reST_ref. -.SS Basic Markups (block) -.sp -This is a simple sentence. -.nf -sentence with -newlines -(reST) -.fi -.sp -.sp -Sentence with -hard\-wrap (markdown, trailing two spaces) -.INDENT 0.0 -.INDENT 3.5 -block quote -second line -.INDENT 0.0 -.INDENT 3.5 -nested quote -.UNINDENT -.UNINDENT -.UNINDENT -.UNINDENT - -.sp -.ce ----- - -.ce 0 -.sp -.INDENT 0.0 -.INDENT 3.5 -Block quote after raw\-html directive -.UNINDENT -.UNINDENT -.SS List -.SS Unordered list -.INDENT 0.0 -.IP \(bu 2 -unordered list -new line -.IP \(bu 2 -next item -.INDENT 2.0 -.IP \(bu 2 -nested list -with new line -.IP \(bu 2 -nested list item 2 -.UNINDENT -.IP \(bu 2 -original depth -.INDENT 2.0 -.IP 1. 3 -ordered list item -.IP 2. 3 -second -with new line -.UNINDENT -.IP \(bu 2 -original depth again -.UNINDENT -.SS Ordered list -.INDENT 0.0 -.IP 1. 3 -ordered list -in new line -.IP 2. 3 -second item -.INDENT 3.0 -.IP \(bu 2 -nested unordered list -.IP \(bu 2 -second item -with new line -.UNINDENT -.IP 3. 3 -original depth -.INDENT 3.0 -.IP 1. 3 -nested ordered list -with new line -.IP 2. 3 -again -.UNINDENT -.IP 4. 3 -original depth again -.UNINDENT -.SS Code Block -.sp -Simple, indented code block -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -pip install sphinx -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Code block with triple backticks and language. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -def a(n: int) \-> None: - for i in range(n): - print(i) -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Triple\-tildes (\fB~~~\fP) are also available. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -def a(n: int) \-> None: - for i in range(n): - print(i) -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Here is reST style code block. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -if True: - print(\(aq\en\(aq) -.ft P -.fi -.UNINDENT -.UNINDENT -.SS Extensions -.SS Table (Markdown\-Style) -.sp -(cell\-alignment is not supported currently) -.TS -center; -|l|l|l|. -_ -T{ -Table Header 1 -T} T{ -Table Header 2 -T} T{ -Table Header 3 -T} -_ -T{ -normal -T} T{ -\fIitalic\fP -T} T{ -\fBbold\fP -T} -_ -T{ -\fBcode\fP -T} T{ -T} T{ -T} -_ -.TE -.SS Math -.sp -This is E = mc^2 inline math. -.sp -The below is math\-block (markdown\-style). -.sp -.ce - -.ce 0 -.sp -The below is reST\-style math\-block. -.sp -.ce - -.ce 0 -.SS Footnote -.sp -Footnote[2] and footnote[3] with markdown. -.sp -Footnote with reST[1]\&. -.sp - -.IP [1] 5 -reST footnote -.IP [2] 5 -footnote 1 -.IP [3] 5 -footnote key -.SS Change Log -.SS Version 0.2 -.sp -(next version) -.SS Version 0.1.5 (2016\-06\-21) -.INDENT 0.0 -.IP \(bu 2 -Support multiple backticks in inline code, like: -.UNINDENT -.SS Version 0.1.4 (2016\-06\-08) -.INDENT 0.0 -.IP \(bu 2 -Support indented directives/reST\-comments -.IP \(bu 2 -Support role\-name after backticks (\fB\(gatext\(ga:role: style\fP) -.UNINDENT -.SS Version 0.1.3 (2016\-06\-02) -.INDENT 0.0 -.IP \(bu 2 -Remove extra escaped\-spaces (\(aq\(aq) -.INDENT 2.0 -.IP \(bu 2 -before and after normal spaces -.IP \(bu 2 -at the beginning of lines -.IP \(bu 2 -before dots -.UNINDENT -.UNINDENT -.SS Version 0.1.2 (2016\-06\-01) -.INDENT 0.0 -.IP \(bu 2 -Add reST\(aqs \fB::\fP marker support -.IP \(bu 2 -Add options to disable emphasis by underscore (\fB_\fP or \fB__\fP) -.UNINDENT -.SS Version 0.1.1 (2016\-05\-30) -.INDENT 0.0 -.IP \(bu 2 -Fix Bug: when code or link is placed at the end of line, spaces to the next word is disappeared -.UNINDENT -.SS Version 0.1 (2016\-05\-30) -.sp -First public release. -.INDENT 0.0 -.IP \(bu 2 -genindex -.IP \(bu 2 -modindex -.IP \(bu 2 -search -.UNINDENT -.SH AUTHOR -Hiroyuki Takagi -.SH COPYRIGHT -2016, Hiroyuki Takagi -.\" Generated by docutils manpage writer. -. |