rst2html(1)

📦
version 0.23 · 6 versions
, in ubuntu stonking

💖 rst2html(1) 💖

bestie, you just opened the manual page for rst2html(1), and it lives in the text processing corner of the man-page universe. It's giving glow-up for your plain text files, no cap. 🦋

✨ NAME ✨

rst2html — convert reST documents to XHTML 🎀

Like, the whole entire job in one line: reST goes in, XHTML comes out. That's it. That's the gig. 💅

✨ SYNOPSIS ✨

rst2html [options] [<source> [<destination>]]

okay so look at that. [options] are optional (iconic behaviour), [<source>] is optional, [<destination>] is optional, and if you pass nothing at all it still runs because life finds a way. 🌈

✨ DESCRIPTION ✨

It generates HTML documents from standalone reStructuredText sources — the docs live at https://docutils.sourceforge.io/docs/user/html.html#html if you wanna go read the whole lore. 📚✨

It reads from source, and if you don't hand it a source, the default is stdin (so it'll just sip whatever you pipe into it, lowkey thirsty behaviour 🥤). It writes to destination, and if you don't give it a destination, the default is stdout — meaning it'll just spill the HTML right into your terminal, main character energy, no filter. 💀

Want the full settings reference, like every knob and dial and vibe? It's at https://docutils.sourceforge.io/docs/user/config.html. Go there. It's a whole thing. 🫶

✨ OPTIONS ✨

okay bestie this is the ✨big one✨, every single flag rst2html will accept. no skimming, we're going through all of them 💅

🎀 General Docutils Options 🎀

  • --output-path=<destination>, --output=<destination> — where the output goes. this one makes the old <destination> positional argument obsolete, so don't @ it. Default: None (that means stdout, i.e. it just yells into your terminal 🗣️).
  • --title=<title> — set the document title as metadata.
  • --generator, -g — drop a "Generated by Docutils" credit in there, with a link and everything. iconic behavior.
  • --no-generator — no generator credit. we keep it mysterious 🫥
  • --date, -d — slap the date at the end of the document (in UTC).
  • --time, -t — the time & date, both, UTC. so extra of it.
  • --no-datestamp — no datestamp of any kind. not one. zero. 💀
  • --root-prefix=<path> — the base directory for absolute paths when it's reading from your local filesystem. Default: "".
  • --source-link, -s — include a "View document source" link.
  • --source-url=<URL> — use <URL> for the source link; heads up, this implies --source-link.
  • --no-source-link — no "View document source" link, sorry gorgeous 🙈
  • --toc-entry-backlinks — link from section headers back to TOC entries. (this is the default ✨)
  • --toc-top-backlinks — link from section headers to the top of the TOC instead.
  • --no-toc-backlinks — kill the backlinks to the table of contents entirely.
  • --footnote-backlinks — link from footnotes/citations back to their references. (default 🌸)
  • --no-footnote-backlinks — no backlinks from footnotes and citations.
  • --section-numbering — turns on section numbering, done by Docutils. (default)
  • --no-section-numbering — turns section numbering off.
  • --strip-comments — yank the comment elements out of the document tree.
  • --leave-comments — leave comment elements right where they are. (default)
  • --strip-elements-with-class=<class> — removes every element with classes="<class>" from the document tree. > Warning: potentially dangerous; use with caution. (Multiple-use option — yes you can stack it, but careful bestie.)
  • --strip-class=<class> — removes 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 above <level>. your choices: "info" or "1", "warning"/"2" (default), "error"/"3", "severe"/"4", "none"/"5".
  • --verbose, -v — report all the system messages. (Same as "--report=1".)
  • --quiet, -q — report no system messages. silence, but make it glamorous. (Same as "--report=5".)
  • --halt=<level> — halt execution at system messages at or above <level>. levels work the same as --report. Default: 4 (severe).
  • --strict — halt at the slightest problem, we are not playing. Same as "--halt=info".
  • --exit-status=<level> — enables 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 — debug output off. (default)
  • --warnings=<file> — send the output of system messages to <file>.
  • --traceback — enable Python tracebacks when Docutils gets halted.
  • --no-traceback — Python tracebacks off. (default)
  • --input-encoding=<name[:handler]> — specify the encoding, and optionally the error handler, of the input text. Default: utf-8.
  • --output-encoding=<name[:handler]> — same deal but for the output text encoding (and optionally its error handler). Default: utf-8.
  • --error-encoding=<name[:handler]>, -e <name[:handler]> — the text encoding and optionally the error handler for error output. Default: system encoding.
  • --language=<tag>, -l <tag> — specify the language as a BCP 47 language tag. Default: en.
  • --record-dependencies=<file> — write the output file dependencies to <file>.
  • --config=<file> — read configuration settings from <file>, if it exists.
  • --version, -V — show this program's version number and dip. ✌️
  • --help, -h — show this help message and dip.

🦋 Generic Parser Options 🦋

  • --no-file-insertion — disables directives that insert the contents of an external file; they get replaced with a "warning" system message.
  • --file-insertion-enabled — enables those file-inserting directives. (default)
  • --no-raw — disables the "raw" directive; gets replaced with a "warning" system message.
  • --raw-enabled — enables the "raw" directive. (default)
  • --line-length-limit=<length> — the maximal number of characters in one input line. Default 10 000.
  • --legacy-ids — keeps identifiers backwards compatible. Default.
  • --matching-ids — explicit targets use identifiers that match the reference name.
  • --validate — validate the document tree after parsing.
  • --no-validation — don't validate the document tree. (default)

🌈 reStructuredText Parser Options 🌈

  • --pep-references — recognize and link to standalone PEP references (like "PEP 258").
  • --pep-base-url=<URL> — the base URL for PEP references (default "https://peps.python.org/").
  • --pep-file-url-template=<URL> — the template for the PEP file part of the URL. (default "pep-%04d")
  • --rfc-references — recognize and link to standalone RFC references (like "RFC 822").
  • --rfc-base-url=<URL> — the base URL for RFC references (default "https://tools.ietf.org/html/").
  • --tab-width=<width> — how many spaces a tab expands to (default 8).
  • --trim-footnote-reference-space — remove the spaces before footnote references.
  • --leave-footnote-reference-space — leave those spaces alone.
  • --syntax-highlight=<format> — the token name set used for parsing code with Pygments. pick one of "long", "short", or "none" (no parsing at all). Default is "long".
  • --smart-quotes=<yes/no/alt> — turns straight quotation marks into typographic form ✨ one of "yes", "no", "alt[ernative]" (default "no").
  • --smartquotes-locales=<language:quotes[,language:quotes,...]> — which characters count as "smart quotes" for a given <language>.
  • --word-level-inline-markup — inline markup is only recognized at word boundaries (right next to punctuation or whitespace). force character-level inline markup recognition with "" (backslash + space). this is the Default.
  • --character-level-inline-markup — inline markup gets recognized anywhere, no matter what's around it. you must use backslash-escapes to stop markup from being recognized where you don't want it. useful for East Asian languages. Experimental, so bestie, tread carefully 👀

👑 Standalone Reader Options 👑

  • --no-doc-title — disables the promotion of a lone top-level section title to document title (and the follow-up where the next section title becomes the document subtitle; this promotion is enabled by default).
  • --no-doc-info — disables the bibliographic field list transform (which is enabled by default).
  • --section-subtitles — activates promoting lone subsection titles to section subtitles (disabled by default).
  • --no-section-subtitles — deactivates that lone-subsection-title promotion.

💖 HTML Writer Options 💖

  • --template=<file> — the template file. (UTF-8 encoded, default: "/usr/share/docutils/writers/html4css1/template.txt")
  • --stylesheet=<URL[,URL,...]> — comma separated list of stylesheet URLs. overrides whatever --stylesheet and --stylesheet-path said before.
  • --stylesheet-path=<file[,file,...]> — comma separated list of stylesheet paths. relative paths get expanded if a matching file turns up in --stylesheet-dirs. with --link-stylesheet, the path gets rewritten relative to the output HTML file. (default: "html4css1.css")
  • --stylesheet-dirs=<dir[,dir,...]> — comma-separated list of directories where stylesheets live. used by --stylesheet-path when it's expanding relative path arguments. (default: ".,/usr/share/docutils/writers/html4css1,/usr/share/docutils/writers/html5_polyglot")
  • --embed-stylesheet — embeds the stylesheet(s) right into the output HTML file. the stylesheet files have to be reachable during processing. (default)
  • --link-stylesheet — links to the stylesheet(s) in the output HTML file instead.
  • --initial-header-level=<level> — sets the initial header level. does not affect the document title & subtitle (see --no-doc-title). (default: 1 for "<h1>")
  • --footnote-references=<format> — the format for footnote references, either "superscript" or "brackets". (default: "brackets")
  • --attribution=<format> — the format for block quote attributions: "dash" (em-dash prefix), "parentheses"/"parens", or "none". (default: "dash")
  • --compact-lists — removes the extra vertical whitespace between items of "simple" bullet lists and enumerated lists. (default)
  • --no-compact-lists — disables those compact simple bullet and enumerated lists.
  • --compact-field-lists — removes the extra vertical whitespace between items of simple field lists. (default)
  • --no-compact-field-lists — disables compact simple field lists.
  • --table-style=<style> — the class value(s) assigned to all tables. defined styles: borderless, booktabs, align-left, align-center, align-right, colwidths-auto, colwidths-grid.
  • --math-output=<format[option(s)]> — the math output format, one of "MathML", "HTML", "MathJax", or "LaTeX", plus its 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 so the harvesters get confused 🥳 while still keeping email links usable in standards-compliant browsers.

🍓 HTML4 Writer Options 🍓

  • --field-name-limit=<level> — sets the maximum width (in characters) for one-column field names. longer field names will span an entire row of the table used to render that field list. Default is 14 characters. use 0 for "no limit".
  • --option-limit=<level> — sets the maximum width (in characters) for options inside 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".

and that's the whole page bestie, you made it to the end 🎉💜 this one's footer is just rst2html(1) doing its little page-name thing down at the bottom — source docs, version and date and all — so go live your truth and render that HTML, no cap ✨🦋👑

📦 where this page comes from