diff options
author | milde <milde@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> | 2023-02-06 21:04:00 +0000 |
---|---|---|
committer | milde <milde@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> | 2023-02-06 21:04:00 +0000 |
commit | cd03b1f0575deb1fa36a9cd07e2230b156a6c053 (patch) | |
tree | 175c6fc1a165a924f6fad95fcac01ab1ccd37329 | |
parent | 151057de56d9489200d06d939f7460c71ceab2f4 (diff) | |
download | docutils-cd03b1f0575deb1fa36a9cd07e2230b156a6c053.tar.gz |
New functions for use as `rst2*` "console_scripts entry points".
The new functions allow the installation of `rst2*` command line scripts
via standard `entry points`__ instead of the current "scripts" list in
``setup.py`` after a transition period (cf. [feature-requests:#88]).
+ Works also for Windows.
+ Allows shorter command names (drop the extension), already in use
in Debian and Ubuntu.
__ https://packaging.python.org/en/latest/specifications/entry-points/
git-svn-id: https://svn.code.sf.net/p/docutils/code/trunk@9325 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
-rw-r--r-- | docutils/HISTORY.txt | 1 | ||||
-rw-r--r-- | docutils/RELEASE-NOTES.txt | 27 | ||||
-rw-r--r-- | docutils/docs/user/tools.txt | 17 | ||||
-rw-r--r-- | docutils/docutils/core.py | 60 | ||||
-rw-r--r-- | docutils/test/data/help/rst2html.txt | 211 | ||||
-rw-r--r-- | docutils/test/data/help/rst2latex.txt | 253 | ||||
-rw-r--r-- | docutils/test/test_CLI.py | 38 |
7 files changed, 579 insertions, 28 deletions
diff --git a/docutils/HISTORY.txt b/docutils/HISTORY.txt index e48567485..20e79dc21 100644 --- a/docutils/HISTORY.txt +++ b/docutils/HISTORY.txt @@ -24,6 +24,7 @@ Changes Since 0.19 - Added new `publish_bytes()` function to explicitly return output as binary data in a `bytes` object. + - New functions `rst2…()` for use as "console_scripts" `entry point`_. * docutils/languages/ docutils/parsers/rst/languages/ diff --git a/docutils/RELEASE-NOTES.txt b/docutils/RELEASE-NOTES.txt index 6762d9ff2..67c7c5638 100644 --- a/docutils/RELEASE-NOTES.txt +++ b/docutils/RELEASE-NOTES.txt @@ -22,10 +22,12 @@ Future changes * Usage: - - The ``rst2*.py`` `front end tools`_ will be renamed to ``rst2*`` - (dropping the ``.py`` extension). [#]_ - You may use ``docutils`` [#]_ as a future-proof command name, - for example: + - Docutils 0.21 will provide ``rst2*`` `"console_scripts" entry + points`_ (without the ``.py`` extension) instead of installing the + ``rst2*.py`` `front end tools`_ in the binary PATH. [#]_ + + You may use the `generic command line front end tool`_ as a + future-proof command, for example: .. code:: diff @@ -37,18 +39,21 @@ Future changes available via ``python -m docutils.writers.odf_odt.prepstyles``. The ``rstpep2html.py`` script will be retired. - Use ``docutils --reader=pep --writer=pep_html`` for a PEP preview. [#]_ + Use ``docutils --reader=pep --writer=pep_html`` for a PEP preview + (the final rendering is done by a Sphinx-based build system, + cf. :PEP:`676`). + .. [#] Some Linux distributions already use the short names. - .. [#] The `generic command line front end tool`_. - .. [#] The final rendering is done by a Sphinx-based build system - (see :PEP:`676`). + .. _"console_scripts" entry points: + https://packaging.python.org/en/latest/specifications/entry-points/ + + - The `default HTML writer`__ will change in Docutils 2.0: - - The `default HTML writer`__ will change in Docutils 2.0. + The rst2html_ front end and ``get_writer_by_name('html')`` select + "html4css1" now and will select "html5" in Docutils 2.0 and later. - * The rst2html_ front end and ``get_writer_by_name('html')`` select - "html4css1" now and will select "html5" in Docutils 2.0 and later. * Use rst2html4_, ``docutils --writer=html4``, or ``get_writer_by_name('html4')`` if you depend on stability of the generated HTML code, e.g. because you use a custom style sheet or diff --git a/docutils/docs/user/tools.txt b/docutils/docs/user/tools.txt index 28456c47b..9a9078e91 100644 --- a/docutils/docs/user/tools.txt +++ b/docutils/docs/user/tools.txt @@ -13,11 +13,9 @@ .. contents:: .. note:: - Docutils front-end tool support is currently `under discussion`__. - Tool names, install details and the set of auto-installed tools - will `change in future Docutils versions`__. + Docutils front-end tool names, install details and the set of + auto-installed tools will `change in Docutils 0.21`__. - __ https://sourceforge.net/p/docutils/feature-requests/88/ __ ../../RELEASE-NOTES.html#future-changes -------------- @@ -73,11 +71,12 @@ list. Generic Command Line Front End ============================== -:Readers: Standalone (default), PEP -:Parsers: reStructuredText (default), Markdown (requires 3rd party packages) -:Writers: html_, html4css1_, html5_ (default), latex2e_, manpage_, - odt_, pep_html_, pseudo-xml_, s5_html_, xelatex_, xml_, -:Config_: `[docutils application]`_ +:CLI name: ``docutils`` +:Readers: Standalone (default), PEP +:Parsers: reStructuredText (default), Markdown (requires 3rd party packages) +:Writers: html_, html4css1_, html5_ (default), latex2e_, manpage_, + odt_, pep_html_, pseudo-xml_, s5_html_, xelatex_, xml_, +:Config_: `[docutils application]`_ Since Docutils 0.19, you can start the generic front end like:: diff --git a/docutils/docutils/core.py b/docutils/docutils/core.py index 4629b0b23..d9b62860c 100644 --- a/docutils/docutils/core.py +++ b/docutils/docutils/core.py @@ -15,6 +15,7 @@ custom component objects first, and pass *them* to __docformat__ = 'reStructuredText' +import locale import pprint import os import sys @@ -227,7 +228,7 @@ class Publisher: output = self.writer.write(self.document, self.destination) self.writer.assemble_parts() except SystemExit as error: - exit = 1 + exit = True exit_status = error.code except Exception as error: if not self.settings: # exception too early to report nicely @@ -757,3 +758,60 @@ def publish_programmatically(source_class, source, source_path, publisher.set_destination(destination, destination_path) output = publisher.publish(enable_exit_status=enable_exit_status) return output, publisher + + +# "Entry points" with functionality of the "tools/rst2*.py" scripts +# cf. https://packaging.python.org/en/latest/specifications/entry-points/ + +def rst2something(writer, documenttype, doc_path=''): + # Helper function for the common parts of rst2... + # writer: writer name + # documenttype: output document type + # doc_path: documentation path (relative to the documentation root) + description = ( + f'Generate {documenttype} documents ' + 'from standalone reStructuredText sources ' + f'<https://docutils.sourceforge.io/docs/{doc_path}>. ' + + default_description) + locale.setlocale(locale.LC_ALL, '') + publish_cmdline(writer_name=writer, description=description) + + +def rst2html(): + rst2something('html', 'HTML', 'user/html.html#html') + + +def rst2html4(): + rst2something('html4', 'XHTML 1.1', 'user/html.html#html4css1') + + +def rst2html5(): + rst2something('html5', 'HTML5', 'user/html.html#html5-polyglot') + + +def rst2latex(): + rst2something('latex', 'LaTeX', 'user/latex.html') + + +def rst2man(): + rst2something('manpage', 'Unix manual (troff)', 'user/manpage.html') + + +def rst2odt(): + rst2something('odt', 'OpenDocument text (ODT)', 'user/odt.html') + + +def rst2pseudoxml(): + rst2something('pseudoxml', 'pseudo-XML (test)', 'ref/doctree.html') + + +def rst2s5(): + rst2something('s5', 'S5 HTML slideshow', 'user/slide-shows.html') + + +def rst2xetex(): + rst2something('xetex', 'LaTeX (XeLaTeX/LuaLaTeX)', 'user/latex.html') + + +def rst2xml(): + rst2something('xml', 'Docutils-native XML', 'ref/doctree.html') diff --git a/docutils/test/data/help/rst2html.txt b/docutils/test/data/help/rst2html.txt new file mode 100644 index 000000000..fc4975991 --- /dev/null +++ b/docutils/test/data/help/rst2html.txt @@ -0,0 +1,211 @@ +Usage +===== + rst2html [options] [<source> [<destination>]] + +Generate HTML documents from standalone reStructuredText sources +<https://docutils.sourceforge.io/docs/user/html.html#html>. Reads from +<source> (default is stdin) and writes to <destination> (default is stdout). +See https://docutils.sourceforge.io/docs/user/config.html for a detailed +settings reference. + +Options +======= +General Docutils Options +------------------------ +--title=TITLE Specify the document title as metadata. +--generator, -g Include a "Generated by Docutils" credit and link. +--no-generator Do not include a generator credit. +--date, -d Include the date at the end of the document (UTC). +--time, -t Include the time & date (UTC). +--no-datestamp Do not include a datestamp of any kind. +--source-link, -s Include a "View document source" link. +--source-url=<URL> Use <URL> for a source link; implies --source-link. +--no-source-link Do not include a "View document source" link. +--toc-entry-backlinks Link from section headers to TOC entries. (default) +--toc-top-backlinks Link from section headers to the top of the TOC. +--no-toc-backlinks Disable backlinks to the table of contents. +--footnote-backlinks Link from footnotes/citations to references. (default) +--no-footnote-backlinks + Disable backlinks from footnotes and citations. +--section-numbering Enable section numbering by Docutils. (default) +--no-section-numbering Disable section numbering by Docutils. +--strip-comments Remove comment elements from the document tree. +--leave-comments Leave comment elements in the document tree. (default) +--strip-elements-with-class=<class> + Remove all elements with classes="<class>" from the + document tree. Warning: potentially dangerous; use + with caution. (Multiple-use option.) +--strip-class=<class> Remove all classes="<class>" attributes from elements + in the document tree. Warning: potentially dangerous; + use with caution. (Multiple-use option.) +--report=<level>, -r <level> + Report system messages at or higher than <level>: + "info" or "1", "warning"/"2" (default), "error"/"3", + "severe"/"4", "none"/"5" +--verbose, -v Report all system messages. (Same as "--report=1".) +--quiet, -q Report no system messages. (Same as "--report=5".) +--halt=<level> Halt execution at system messages at or above <level>. + Levels as in --report. Default: 4 (severe). +--strict Halt at the slightest problem. Same as "--halt=info". +--exit-status=<level> Enable a non-zero exit status for non-halting system + messages at or above <level>. Default: 5 (disabled). +--debug Enable debug-level system messages and diagnostics. +--no-debug Disable debug output. (default) +--warnings=<file> Send the output of system messages to <file>. +--traceback Enable Python tracebacks when Docutils is halted. +--no-traceback Disable Python tracebacks. (default) +--input-encoding=<name[:handler]>, -i <name[:handler]> + Specify the encoding and optionally the error handler + of input text. Default: <auto-detect>:strict. +--input-encoding-error-handler=INPUT_ENCODING_ERROR_HANDLER + Specify the error handler for undecodable characters. + Choices: "strict" (default), "ignore", and "replace". +--output-encoding=<name[:handler]>, -o <name[:handler]> + Specify the text encoding and optionally the error + handler for output. Default: utf-8:strict. +--output-encoding-error-handler=OUTPUT_ENCODING_ERROR_HANDLER + Specify error handler for unencodable output + characters; "strict" (default), "ignore", "replace", + "xmlcharrefreplace", "backslashreplace". +--error-encoding=<name[:handler]>, -e <name[:handler]> + Specify text encoding and optionally error handler for + error output. Default: utf-8:backslashreplace. +--error-encoding-error-handler=ERROR_ENCODING_ERROR_HANDLER + Specify the error handler for unencodable characters + in error output. Default: backslashreplace. +--language=<name>, -l <name> + Specify the language (as BCP 47 language tag). + Default: en. +--record-dependencies=<file> + Write output file dependencies to <file>. +--config=<file> Read configuration settings from <file>, if it exists. +--version, -V Show this program's version number and exit. +--help, -h Show this help message and exit. + +Generic Parser Options +---------------------- +--no-file-insertion Disable directives that insert the contents of an + external file; replaced with a "warning" system + message. +--file-insertion-enabled + Enable directives that insert the contents of an + external file. (default) +--no-raw Disable the "raw" directive; replaced with a "warning" + system message. +--raw-enabled Enable the "raw" directive. (default) +--line-length-limit=<length> + Maximal number of characters in an input line. Default + 10 000. + +reStructuredText Parser Options +------------------------------- +--pep-references Recognize and link to standalone PEP references (like + "PEP 258"). +--pep-base-url=<URL> Base URL for PEP references (default + "https://peps.python.org/"). +--pep-file-url-template=<URL> + Template for PEP file part of URL. (default + "pep-%04d") +--rfc-references Recognize and link to standalone RFC references (like + "RFC 822"). +--rfc-base-url=<URL> Base URL for RFC references (default + "https://tools.ietf.org/html/"). +--tab-width=<width> Set number of spaces for tab expansion (default 8). +--trim-footnote-reference-space + Remove spaces before footnote references. +--leave-footnote-reference-space + Leave spaces before footnote references. +--syntax-highlight=<format> + Token name set for parsing code with Pygments: one of + "long", "short", or "none" (no parsing). Default is + "long". +--smart-quotes=<yes/no/alt> + Change straight quotation marks to typographic form: + one of "yes", "no", "alt[ernative]" (default "no"). +--smartquotes-locales=<language:quotes[,language:quotes,...]> + Characters to use as "smart quotes" for <language>. +--word-level-inline-markup + Inline markup recognized at word boundaries only + (adjacent to punctuation or whitespace). Force + character-level inline markup recognition with "\ " + (backslash + space). Default. +--character-level-inline-markup + Inline markup recognized anywhere, regardless of + surrounding characters. Backslash-escapes must be used + to avoid unwanted markup recognition. Useful for East + Asian languages. Experimental. + +Standalone Reader Options +------------------------- +--no-doc-title Disable the promotion of a lone top-level section + title to document title (and subsequent section title + to document subtitle promotion; enabled by default). +--no-doc-info Disable the bibliographic field list transform + (enabled by default). +--section-subtitles Activate the promotion of lone subsection titles to + section subtitles (disabled by default). +--no-section-subtitles Deactivate the promotion of lone subsection titles. + +HTML Writer Options +------------------- +--template=<file> Template file. (UTF-8 encoded, default: [...]) +--stylesheet=<URL[,URL,...]> + Comma separated list of stylesheet URLs. Overrides + previous --stylesheet and --stylesheet-path settings. +--stylesheet-path=<file[,file,...]> + Comma separated list of stylesheet paths. Relative + paths are expanded if a matching file is found in the + --stylesheet-dirs. With --link-stylesheet, the path is + rewritten relative to the output HTML file. (default: + "html4css1.css") +--stylesheet-dirs=<dir[,dir,...]> + Comma-separated list of directories where stylesheets + are found. Used by --stylesheet-path when expanding + relative path arguments. (default: [...]) +--embed-stylesheet Embed the stylesheet(s) in the output HTML file. The + stylesheet files must be accessible during processing. + (default) +--link-stylesheet Link to the stylesheet(s) in the output HTML file. +--initial-header-level=<level> + Specify the initial header level. Does not affect + document title & subtitle (see --no-doc-title). + (default: 1 for "<h1>") +--footnote-references=<format> + Format for footnote references: one of "superscript" + or "brackets". (default: "brackets") +--attribution=<format> Format for block quote attributions: one of "dash" + (em-dash prefix), "parentheses"/"parens", or "none". + (default: "dash") +--compact-lists Remove extra vertical whitespace between items of + "simple" bullet lists and enumerated lists. (default) +--no-compact-lists Disable compact simple bullet and enumerated lists. +--compact-field-lists Remove extra vertical whitespace between items of + simple field lists. (default) +--no-compact-field-lists + Disable compact simple field lists. +--table-style=TABLE_STYLE + Added to standard table classes. Defined styles: + borderless, booktabs, align-left, align-center, align- + right, colwidths-auto, colwidths-grid. +--math-output=MATH_OUTPUT + Math output format (one of "MathML", "HTML", + "MathJax", or "LaTeX") and option(s). (default: "HTML + math.css") +--xml-declaration Prepend an XML declaration (default). +--no-xml-declaration Omit the XML declaration. +--cloak-email-addresses + Obfuscate email addresses to confuse harvesters while + still keeping email links usable with standards- + compliant browsers. + +HTML4 Writer Options +-------------------- +--field-name-limit=<level> + Specify the maximum width (in characters) for one- + column field names. Longer field names will span an + entire row of the table used to render the field list. + Default is 14 characters. Use 0 for "no limit". +--option-limit=<level> Specify the maximum width (in characters) for options + in option lists. Longer options will span an entire + row of the table used to render the option list. + Default is 14 characters. Use 0 for "no limit". diff --git a/docutils/test/data/help/rst2latex.txt b/docutils/test/data/help/rst2latex.txt new file mode 100644 index 000000000..12ea0d40c --- /dev/null +++ b/docutils/test/data/help/rst2latex.txt @@ -0,0 +1,253 @@ +Usage +===== + rst2latex [options] [<source> [<destination>]] + +Generate LaTeX documents from standalone reStructuredText sources +<https://docutils.sourceforge.io/docs/user/latex.html>. Reads from <source> +(default is stdin) and writes to <destination> (default is stdout). See +https://docutils.sourceforge.io/docs/user/config.html for a detailed settings +reference. + +Options +======= +General Docutils Options +------------------------ +--title=TITLE Specify the document title as metadata. +--generator, -g Include a "Generated by Docutils" credit and link. +--no-generator Do not include a generator credit. +--date, -d Include the date at the end of the document (UTC). +--time, -t Include the time & date (UTC). +--no-datestamp Do not include a datestamp of any kind. +--source-link, -s Include a "View document source" link. +--source-url=<URL> Use <URL> for a source link; implies --source-link. +--no-source-link Do not include a "View document source" link. +--toc-entry-backlinks Link from section headers to TOC entries. (default) +--toc-top-backlinks Link from section headers to the top of the TOC. +--no-toc-backlinks Disable backlinks to the table of contents. +--footnote-backlinks Link from footnotes/citations to references. (default) +--no-footnote-backlinks + Disable backlinks from footnotes and citations. +--section-numbering Enable section numbering by Docutils. (default) +--no-section-numbering Disable section numbering by Docutils. +--strip-comments Remove comment elements from the document tree. +--leave-comments Leave comment elements in the document tree. (default) +--strip-elements-with-class=<class> + Remove all elements with classes="<class>" from the + document tree. Warning: potentially dangerous; use + with caution. (Multiple-use option.) +--strip-class=<class> Remove all classes="<class>" attributes from elements + in the document tree. Warning: potentially dangerous; + use with caution. (Multiple-use option.) +--report=<level>, -r <level> + Report system messages at or higher than <level>: + "info" or "1", "warning"/"2" (default), "error"/"3", + "severe"/"4", "none"/"5" +--verbose, -v Report all system messages. (Same as "--report=1".) +--quiet, -q Report no system messages. (Same as "--report=5".) +--halt=<level> Halt execution at system messages at or above <level>. + Levels as in --report. Default: 4 (severe). +--strict Halt at the slightest problem. Same as "--halt=info". +--exit-status=<level> Enable a non-zero exit status for non-halting system + messages at or above <level>. Default: 5 (disabled). +--debug Enable debug-level system messages and diagnostics. +--no-debug Disable debug output. (default) +--warnings=<file> Send the output of system messages to <file>. +--traceback Enable Python tracebacks when Docutils is halted. +--no-traceback Disable Python tracebacks. (default) +--input-encoding=<name[:handler]>, -i <name[:handler]> + Specify the encoding and optionally the error handler + of input text. Default: <auto-detect>:strict. +--input-encoding-error-handler=INPUT_ENCODING_ERROR_HANDLER + Specify the error handler for undecodable characters. + Choices: "strict" (default), "ignore", and "replace". +--output-encoding=<name[:handler]>, -o <name[:handler]> + Specify the text encoding and optionally the error + handler for output. Default: utf-8:strict. +--output-encoding-error-handler=OUTPUT_ENCODING_ERROR_HANDLER + Specify error handler for unencodable output + characters; "strict" (default), "ignore", "replace", + "xmlcharrefreplace", "backslashreplace". +--error-encoding=<name[:handler]>, -e <name[:handler]> + Specify text encoding and optionally error handler for + error output. Default: utf-8:backslashreplace. +--error-encoding-error-handler=ERROR_ENCODING_ERROR_HANDLER + Specify the error handler for unencodable characters + in error output. Default: backslashreplace. +--language=<name>, -l <name> + Specify the language (as BCP 47 language tag). + Default: en. +--record-dependencies=<file> + Write output file dependencies to <file>. +--config=<file> Read configuration settings from <file>, if it exists. +--version, -V Show this program's version number and exit. +--help, -h Show this help message and exit. + +Generic Parser Options +---------------------- +--no-file-insertion Disable directives that insert the contents of an + external file; replaced with a "warning" system + message. +--file-insertion-enabled + Enable directives that insert the contents of an + external file. (default) +--no-raw Disable the "raw" directive; replaced with a "warning" + system message. +--raw-enabled Enable the "raw" directive. (default) +--line-length-limit=<length> + Maximal number of characters in an input line. Default + 10 000. + +reStructuredText Parser Options +------------------------------- +--pep-references Recognize and link to standalone PEP references (like + "PEP 258"). +--pep-base-url=<URL> Base URL for PEP references (default + "https://peps.python.org/"). +--pep-file-url-template=<URL> + Template for PEP file part of URL. (default + "pep-%04d") +--rfc-references Recognize and link to standalone RFC references (like + "RFC 822"). +--rfc-base-url=<URL> Base URL for RFC references (default + "https://tools.ietf.org/html/"). +--tab-width=<width> Set number of spaces for tab expansion (default 8). +--trim-footnote-reference-space + Remove spaces before footnote references. +--leave-footnote-reference-space + Leave spaces before footnote references. +--syntax-highlight=<format> + Token name set for parsing code with Pygments: one of + "long", "short", or "none" (no parsing). Default is + "long". +--smart-quotes=<yes/no/alt> + Change straight quotation marks to typographic form: + one of "yes", "no", "alt[ernative]" (default "no"). +--smartquotes-locales=<language:quotes[,language:quotes,...]> + Characters to use as "smart quotes" for <language>. +--word-level-inline-markup + Inline markup recognized at word boundaries only + (adjacent to punctuation or whitespace). Force + character-level inline markup recognition with "\ " + (backslash + space). Default. +--character-level-inline-markup + Inline markup recognized anywhere, regardless of + surrounding characters. Backslash-escapes must be used + to avoid unwanted markup recognition. Useful for East + Asian languages. Experimental. + +Standalone Reader Options +------------------------- +--no-doc-title Disable the promotion of a lone top-level section + title to document title (and subsequent section title + to document subtitle promotion; enabled by default). +--no-doc-info Disable the bibliographic field list transform + (enabled by default). +--section-subtitles Activate the promotion of lone subsection titles to + section subtitles (disabled by default). +--no-section-subtitles Deactivate the promotion of lone subsection titles. + +LaTeX-Specific Options +---------------------- +--documentclass=DOCUMENTCLASS + Specify LaTeX documentclass. Default: "article". +--documentoptions=DOCUMENTOPTIONS + Specify document options. Multiple options can be + given, separated by commas. Default: "a4paper". +--footnote-references=<format> + Format for footnote references: one of "superscript" + or "brackets". Default: "superscript". +--use-latex-citations Use \cite command for citations. (future default) +--figure-citations Use figure floats for citations (might get mixed with + real figures). (provisional default) +--attribution=<format> Format for block quote attributions: one of "dash" + (em-dash prefix), "parentheses"/"parens", or "none". + Default: "dash". +--stylesheet=<file[,file,...]> + Specify LaTeX packages/stylesheets. A style is + referenced with "\usepackage" if extension is ".sty" + or omitted and with "\input" else. Overrides previous + --stylesheet and --stylesheet-path settings. +--stylesheet-path=<file[,file,...]> + Comma separated list of LaTeX packages/stylesheets. + Relative paths are expanded if a matching file is + found in the --stylesheet-dirs. With --link- + stylesheet, the path is rewritten relative to the + output *.tex file. +--link-stylesheet Link to the stylesheet(s) in the output file. + (default) +--embed-stylesheet Embed the stylesheet(s) in the output file. + Stylesheets must be accessible during processing. +--stylesheet-dirs=<dir[,dir,...]> + Comma-separated list of directories where stylesheets + are found. Used by --stylesheet-path when expanding + relative path arguments. Default: ".". +--latex-preamble=LATEX_PREAMBLE + Customization by LaTeX code in the preamble. Default: + select PDF standard fonts (Times, Helvetica, Courier). +--template=<file> Specify the template file. Default: "default.tex". +--use-latex-toc Table of contents by LaTeX. (default) +--use-docutils-toc Table of contents by Docutils (without page numbers). +--use-part-section Add parts on top of the section hierarchy. +--use-docutils-docinfo Attach author and date to the document info table. + (default) +--use-latex-docinfo Attach author and date to the document title. +--topic-abstract Typeset abstract as topic. (default) +--use-latex-abstract Use LaTeX abstract environment for the document's + abstract. +--hyperlink-color=HYPERLINK_COLOR + Color of any hyperlinks embedded in text. Default: + "blue" (use "false" to disable). +--hyperref-options=HYPERREF_OPTIONS + Additional options to the "hyperref" package. +--compound-enumerators Enable compound enumerators for nested enumerated + lists (e.g. "1.2.a.ii"). +--no-compound-enumerators + Disable compound enumerators for nested enumerated + lists. (default) +--section-prefix-for-enumerators + Enable section ("." subsection ...) prefixes for + compound enumerators. This has no effect without + --compound-enumerators. +--no-section-prefix-for-enumerators + Disable section prefixes for compound enumerators. + (default) +--section-enumerator-separator=<char> + Set the separator between section number and + enumerator for compound enumerated lists. Default: + "-". +--literal-block-env=LITERAL_BLOCK_ENV + When possible, use the specified environment for + literal-blocks. Default: "" (fall back to "alltt"). +--use-verbatim-when-possible + Deprecated alias for "--literal-block-env=verbatim". +--table-style=<format> Table style. "standard" with horizontal and vertical + lines, "booktabs" (LaTeX booktabs style) only + horizontal lines above and below the table and below + the header, or "borderless". Default: "standard" +--graphicx-option=GRAPHICX_OPTION + LaTeX graphicx package option. Possible values are + "dvipdfmx", "dvips", "dvisvgm", "luatex", "pdftex", + and "xetex".Default: "". +--font-encoding=FONT_ENCODING + LaTeX font encoding. Possible values are "", "T1" + (default), "OT1", "LGR,T1" or any other combination of + options to the `fontenc` package. +--reference-label=REFERENCE_LABEL + Per default the latex-writer puts the reference title + into hyperreferences. Specify "ref*" or "pageref*" to + get the section number or the page number. +--use-bibtex=<style,bibfile[,bibfile,...]> + Specify style and database(s) for bibtex, for example + "--use-bibtex=unsrt,mydb1,mydb2". Provisional! +--legacy-class-functions + Use legacy functions with class value list for + \DUtitle and \DUadmonition. +--new-class-functions Use \DUrole and "DUclass" wrappers for class values. + Place admonition content in an environment. (default) +--legacy-column-widths Use legacy algorithm to determine table column widths. + (provisional default) +--new-column-widths Use new algorithm to determine table column widths. + (future default) +--docutils-footnotes Footnotes with numbers/symbols by Docutils. (default) + (The alternative, --latex-footnotes, is not + implemented yet.) diff --git a/docutils/test/test_CLI.py b/docutils/test/test_CLI.py index 85dd25a58..f88e3e646 100644 --- a/docutils/test/test_CLI.py +++ b/docutils/test/test_CLI.py @@ -30,7 +30,7 @@ if __name__ == '__main__': # so we import the local `docutils` package. sys.path.insert(0, str(Path(__file__).resolve().parents[1])) -from docutils import __main__, frontend +from docutils import __main__, core, frontend # DATA_ROOT is ./test/data/ from the docutils root DATA_ROOT = Path(__file__).parent / 'data' @@ -59,11 +59,11 @@ class CliTests(unittest.TestCase): sys.argv = self.orig_argv locale.setlocale(locale.LC_ALL, 'C') # restore default (C) locale - def test_main_help(self): - # collect help text - sys.argv = ['docutils', '--help'] + def get_help_text(self, prog, entry_point): + # call entry_point function and collect help text + sys.argv = [prog, '--help'] try: - __main__.main() + entry_point() except SystemExit: pass output = sys.stdout.getvalue() @@ -72,15 +72,39 @@ class CliTests(unittest.TestCase): output, flags=re.DOTALL) # normalise error encoding default output = output.replace( - f'{frontend.OptionParser.default_error_encoding}:backslashreplace', + f'{core.OptionParser.default_error_encoding}:backslashreplace', 'utf-8:backslashreplace') + return output + + def test_main_help(self): + # collect help text + output = self.get_help_text('docutils', __main__.main) + # compare to stored version - docutils_txt = DATA_ROOT / 'help' / 'docutils.txt' + docutils_txt = os.path.join(DATA_ROOT, 'help/docutils.txt') with open(docutils_txt, encoding='utf-8') as samplefile: expected = samplefile.read() if expected != output: print_mismatch(expected, output) + def test_rst2html_help(self): + # collect help text + output = self.get_help_text('rst2html', core.rst2html) + # compare to stored version + with open('data/help/rst2html.txt') as samplefile: + expected = samplefile.read() + if expected != output: + print_mismatch(expected, output) + + def test_rst2latex_help(self): + # collect help text + output = self.get_help_text('rst2latex', core.rst2latex) + # compare to stored version + with open('data/help/rst2latex.txt') as samplefile: + expected = samplefile.read() + if expected != output: + print_mismatch(expected, output) + if __name__ == '__main__': unittest.main() |