id       = "docutils"
name     = "Docutils"
homepage = "https://docutils.sourceforge.io"
description = "An open-source text processing system for plaintext documentation."
executables   = ["rst2html", "rst2html4", "rst2html5", "rst2latex", "rst2man", "rst2odt", "rst2pseudoxml", "rst2s5", "rst2xetex", "rst2xml"]

[dotfiles]

# Docutils' official configuration guide identifies ~/.docutils as the
# user-specific implicit config file. /etc/docutils.conf is system-wide and
# ./docutils.conf is project-local, so neither belongs in a user dotfile set.
# https://docutils.sourceforge.io/docs/user/config.html
paths = ["~/.docutils"]
secret = []

[commands]
format = 1
label = "Convert reStructuredText to HTML"
description = "Convert a reStructuredText file to HTML with rst2html. The other rst2* converters take similar options but are not covered; stylesheet directories, math output and footnote tuning are left out."
quality = "ai-draft"
parser = { end_of_options = "--", interleave = "permute", long_equals = true, short_attached = true, short_bundles = false }

[[commands.source]]
id = "help"
kind = "help"
url = "https://docutils.sourceforge.io/docs/user/html.html"
revision = "docutils 0.22 rst2html --help"
evidence = """
  rst2html [options] [<source> [<destination>]]
--output-path=<destination>, --output=<destination>
--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).
--source-link, -s       Include a "View document source" link.
--no-section-numbering  Disable section numbering by Docutils.
--strip-comments        Remove comment elements from the document tree.
--report=<level>, -r <level>
--verbose, -v           Report all system messages.  (Same as "--report=1".)
--quiet, -q             Report no system messages.  (Same as "--report=5".)
--strict                Halt at the slightest problem.  Same as "--halt=info".
--language=<tag>, -l <tag>
--input-encoding=<name[:handler]>
--output-encoding=<name[:handler]>
--tab-width=<width>     Set number of spaces for tab expansion (default 8).
--syntax-highlight=<format>
                        Token name set for parsing code with Pygments: one of
                        "long", "short", or "none" (no parsing). Default is
--smart-quotes=<yes/no/alt>
--stylesheet-path=<file[,file,...]>
--embed-stylesheet      Embed the stylesheet(s) in the output HTML file.  The
--link-stylesheet       Link to the stylesheet(s) in the output HTML file.
--initial-header-level=<level>
"""

[[commands.field]]
id = "source"
label = "reStructuredText file"
description = "Defaults to standard input when empty."
type = "path"
position = 0
path = { kind = "file", role = "input", must_exist = true }
sources = ["help"]

[[commands.field]]
id = "destination"
label = "Output file"
description = "Defaults to standard output when empty."
type = "path"
option = ["--output-path"]
path = { kind = "file", role = "output", must_exist = false }
effect = "overwrite"
sources = ["help"]

[[commands.field]]
id = "title"
label = "Document title"
type = "string"
option = ["--title"]
sources = ["help"]

[[commands.field]]
id = "stylesheet_path"
label = "Stylesheet"
description = "CSS file to use instead of the default."
type = "path"
option = ["--stylesheet-path"]
path = { kind = "file", role = "input", must_exist = true }
sources = ["help"]

[[commands.field]]
id = "link_stylesheet"
label = "Link stylesheet instead of embedding"
type = "boolean"
option = ["--link-stylesheet"]
sources = ["help"]

[[commands.field]]
id = "no_section_numbering"
label = "Disable section numbering"
type = "boolean"
option = ["--no-section-numbering"]
sources = ["help"]

[[commands.field]]
id = "initial_header_level"
label = "Initial header level"
type = "integer"
option = ["--initial-header-level"]
sources = ["help"]

[[commands.field]]
id = "syntax_highlight"
label = "Code highlighting"
type = "enum"
option = ["--syntax-highlight"]
choices = [{ value = "long", label = "Long token names" }, { value = "short", label = "Short token names" }, { value = "none", label = "No highlighting" }]
sources = ["help"]

[[commands.field]]
id = "smart_quotes"
label = "Smart quotes"
type = "enum"
option = ["--smart-quotes"]
choices = [{ value = "yes", label = "Yes" }, { value = "no", label = "No" }, { value = "alt", label = "Alternative" }]
sources = ["help"]

[[commands.field]]
id = "tab_width"
label = "Tab width"
type = "integer"
option = ["--tab-width"]
sources = ["help"]

[[commands.field]]
id = "strict"
label = "Halt at the slightest problem"
type = "boolean"
option = ["--strict"]
sources = ["help"]

[[commands.field]]
id = "quiet"
label = "Report no system messages"
type = "boolean"
option = ["--quiet", "-q"]
sources = ["help"]

[[commands.task]]
id = "to-html"
label = "Convert to HTML"
fields = ["source", "destination", "title", "stylesheet_path", "link_stylesheet"]
required = ["source", "destination"]

[[commands.task]]
id = "check"
label = "Check for problems"
description = "Convert to standard output and halt on any warning."
set = { strict = [true] }
fields = ["source", "strict"]
required = ["source"]

[[commands.group]]
id = "basic"
label = "Basic"
fields = ["source", "destination", "title", "stylesheet_path", "link_stylesheet"]

[[commands.group]]
id = "advanced"
label = "Advanced"
fields = ["no_section_numbering", "initial_header_level", "syntax_highlight", "smart_quotes", "tab_width", "strict", "quiet"]