#!/usr/bin/env python3

"""usage: %s DOC ...

where DOC is the name of a document

"""

import os

import sys

import textwrap

import argparse

try:

    import msvcrt

    msvcrt.setmode(sys.stdout.fileno(), os.O_BINARY)

    msvcrt.setmode(sys.stderr.fileno(), os.O_BINARY)

except ImportError:

    pass

# This script is executed during installs and may not have C extensions

# available. Relax C module requirements.

os.environ['HGMODULEPOLICY'] = 'allow'

# import from the live mercurial repo

sys.path.insert(0, os.path.abspath(".."))

from mercurial import demandimport

demandimport.enable()

from mercurial import (

    commands,

    encoding,

    extensions,

    fancyopts,

    help,

    minirst,

    pycompat,

    ui as uimod,

)

from mercurial.i18n import (

    gettext,

    _,

)

from mercurial.utils import stringutil

table = commands.table

globalopts = commands.globalopts

helptable = help.helptable

loaddoc = help.loaddoc

def get_desc(docstr):

    if not docstr:

        return b"", b""

    # sanitize

    docstr = docstr.strip(b"\n")

    docstr = docstr.rstrip()

    shortdesc = docstr.splitlines()[0].strip()

    i = docstr.find(b"\n")

    if i != -1:

        desc = docstr[i + 2 :]

    else:

        desc = shortdesc

    desc = textwrap.dedent(desc.decode('latin1')).encode('latin1')

    return (shortdesc, desc)

def get_opts(opts):

    for opt in opts:

        if len(opt) == 5:

            shortopt, longopt, default, desc, optlabel = opt

        else:

            shortopt, longopt, default, desc = opt

            optlabel = _(b"VALUE")

        allopts = []

        if shortopt:

            allopts.append(b"-%s" % shortopt)

        if longopt:

            allopts.append(b"--%s" % longopt)

        if isinstance(default, list):

            allopts[-1] += b" <%s[+]>" % optlabel

        elif (default is not None) and not isinstance(default, bool):

            allopts[-1] += b" <%s>" % optlabel

        if b'\n' in desc:

            # only remove line breaks and indentation

            desc = b' '.join(l.lstrip() for l in desc.split(b'\n'))

        if isinstance(default, fancyopts.customopt):

            default = default.getdefaultvalue()

        if default:

            default = stringutil.forcebytestr(default)

            desc += _(b" (default: %s)") % default

        yield (b", ".join(allopts), desc)

def get_cmd(cmd, cmdtable):

    d = {}

    attr = cmdtable[cmd]

    cmds = cmd.lstrip(b"^").split(b"|")

    d[b'cmd'] = cmds[0]

    d[b'aliases'] = cmd.split(b"|")[1:]

    d[b'desc'] = get_desc(gettext(pycompat.getdoc(attr[0])))

    d[b'opts'] = list(get_opts(attr[1]))

    s = b'hg ' + cmds[0]

    if len(attr) > 2:

        if not attr[2].startswith(b'hg'):

            s += b' ' + attr[2]

        else:

            s = attr[2]

    d[b'synopsis'] = s.strip()

    return d

def showdoc(ui, debugcmds=False):

    # print options

    ui.write(minirst.section(_(b"Options")))

    multioccur = False

    for optstr, desc in get_opts(globalopts):

        ui.write(b"%s\n    %s\n\n" % (optstr, desc))

        if optstr.endswith(b"[+]>"):

            multioccur = True

    if multioccur:

        ui.write(_(b"\n[+] marked option can be specified multiple times\n"))

        ui.write(b"\n")

    # print cmds

    ui.write(minirst.section(_(b"Commands")))

    commandprinter(

        ui,

        table,

        minirst.subsection,

        minirst.subsubsection,

        debugcmds=debugcmds,

    )

    # print help topics

    # The config help topic is included in the hgrc.5 man page.

    topics = findtopics(helptable, exclude=[b'config'])

    helpprinter(ui, topics, minirst.section)

    ui.write(minirst.section(_(b"Extensions")))

    ui.write(

        _(

            b"This section contains help for extensions that are "

            b"distributed together with Mercurial. Help for other "

            b"extensions is available in the help system."

        )

    )

    ui.writenoi18n(

        b"\n\n"

        b".. contents::\n"

        b"   :class: htmlonly\n"

        b"   :local:\n"

        b"   :depth: 1\n\n"

    )

    for extensionname in sorted(allextensionnames()):

        mod = extensions.load(ui, extensionname, None)

        ui.write(minirst.subsection(extensionname))

        ext_doc = help.ext_help(ui, mod)

        ui.write(b"%s\n\n" % ext_doc)

        cmdtable = getattr(mod, 'cmdtable', None)

        if cmdtable:

            ui.write(minirst.subsubsection(_(b'Commands')))

            commandprinter(

                ui,

                cmdtable,

                minirst.subsubsubsection,

                minirst.subsubsubsubsection,

                debugcmds=debugcmds,

            )

def showcommandlist(ui, debugcmds=False):

    """Render a plain text list of all command names

    Args:

        ui: the UI object to output to

        debugcmds: whether to include debug commands

    """

    cmdnames = allcommandnames(table, debugcmds=debugcmds)

    for mainname in cmdnames.keys():

        # Make does not like semicolons in filenames (or what it

        # considers as filenames). We use command names as targets so

        # it applies here. For now let's skip commands with semicolons

        # in them (at this time it only includes the `admin::verify`

        # advanced command).

        if b'::' in mainname:

            continue

        ui.write(mainname)

        ui.write(b" ")

def showtopiclist(ui):

    """Render a plain text list of all help topic names

    Args:

        ui: the UI object to output to

    """

    for topic in helptable:

        topicname = topic[0][0]

        if help.filtertopic(ui, topicname):

            continue

        ui.write(topicname)

        ui.write(b" ")

def showextensionlist(ui):

    """Render a plain text list of all extension names

    Args:

        ui: the UI object to output to

    """

    for extensionname in allextensionnames():

        ui.write(extensionname)

        ui.write(b" ")

def showhelpindex(ui, debugcmds=False):

    """Render restructured text for a complete mercurial help index

    This index will show a list of commands, followed by a list of help topics,

    and finally a list of extensions. These lists are split in categories and

    ordered 'nicely' as defined by alphabetical and categeory order.

    Each entry in this index is a reference to the specific help page of the

    command, topic, or extension at hand.

    """

    ui.write(minirst.section(_(b"Mercurial Distributed SCM")))

    missingdoc = _(b"(no help text available)")

    cats, h, syns = help._getcategorizedhelpcmds(ui, table, None)

    ui.write(minirst.subsection(_(b"Commands")))

    for cat in help.CATEGORY_ORDER:

        catfns = sorted(cats.get(cat, []))

        if not catfns:

            continue

        catname = gettext(help.CATEGORY_NAMES[cat])

        ui.write(minirst.subsubsection(catname))

        for c in catfns:

            url = b'hg-%s.html' % c

            ui.write(b" :`%s <%s>`__: %s" % (c, url, h[c]))

            syns[c].remove(c)

            if syns[c]:

                ui.write(_(b" (aliases: *%s*)") % (b', '.join(syns[c])))

            ui.write(b"\n")

        ui.write(b"\n\n")

    ui.write(b"\n\n")

    ui.write(minirst.subsection(_(b"Additional Help Topics")))

    topiccats, topicsyns = help._getcategorizedhelptopics(ui, helptable)

    for cat in help.TOPIC_CATEGORY_ORDER:

        topics = topiccats.get(cat, [])

        if not topics:

            continue

        catname = gettext(help.TOPIC_CATEGORY_NAMES[cat])

        ui.write(minirst.subsubsection(catname))

        for t, desc in topics:

            url = b'topic-%s.html' % t

            ui.write(b" :`%s <%s>`__: %s" % (t, url, desc))

            topicsyns[t].remove(t)

            if topicsyns[t]:

                ui.write(_(b" (aliases: *%s*)") % (b', '.join(topicsyns[t])))

            ui.write(b"\n")

        ui.write(b"\n\n")

    ui.write(b"\n\n")

    # Add an alphabetical list of extensions, categorized by group.

    sectionkeywords = [

        (b"(ADVANCED)", _(b"(ADVANCED)")),

        (b"(EXPERIMENTAL)", _(b"(EXPERIMENTAL)")),

        (b"(DEPRECATED)", _(b"(DEPRECATED)")),

    ]

    extensionsections = [

        (b"Extensions", []),

        (b"Advanced Extensions", []),

        (b"Experimental Extensions", []),

        (b"Deprecated Extensions", []),

    ]

    for extensionname in allextensionnames():

        mod = extensions.load(ui, extensionname, None)

        shortdoc, longdoc = _splitdoc(mod)

        for i, kwds in enumerate(sectionkeywords):

            if any([kwd in shortdoc for kwd in kwds]):

                extensionsections[i + 1][1].append(

                    (extensionname, mod, shortdoc)

                )

                break

        else:

            extensionsections[0][1].append((extensionname, mod, shortdoc))

    for sectiontitle, extinfos in extensionsections:

        ui.write(minirst.subsection(_(sectiontitle)))

        for extinfo in sorted(extinfos, key=lambda ei: ei[0]):

            extensionname, mod, shortdoc = extinfo

            url = b'ext-%s.html' % extensionname

            ui.write(

                minirst.subsubsection(b'`%s <%s>`__' % (extensionname, url))

            )

            ui.write(shortdoc)

            ui.write(b'\n\n')

            cmdtable = getattr(mod, 'cmdtable', None)

            if cmdtable:

                cmdnames = allcommandnames(cmdtable, debugcmds=debugcmds)

                for f in sorted(cmdnames.keys()):

                    d = get_cmd(cmdnames[f], cmdtable)

                    ui.write(b':%s: ' % d[b'cmd'])

                    ui.write(d[b'desc'][0] or (missingdoc + b"\n"))

                    ui.write(b'\n')

            ui.write(b'\n')

def showcommand(ui, mainname):

    # Always pass debugcmds=True so that we find whatever command we are told

    # to display.

    cmdnames = allcommandnames(table, debugcmds=True)

    allnames = cmdnames[mainname]

    d = get_cmd(allnames, table)

    header = _rendertpl(

        'cmdheader.txt',

        {

            'cmdname': mainname,

            'cmdtitle': minirst.section(b'hg ' + mainname),

            'cmdshortdesc': minirst.subsection(d[b'desc'][0]),

            'cmdlongdesc': d[b'desc'][1],

            'cmdsynopsis': d[b'synopsis'],

        },

    )

    ui.write(header.encode())

    _optionsprinter(ui, d, minirst.subsubsection)

    if d[b'aliases']:

        ui.write(minirst.subsubsection(_(b"Aliases")))

        ui.write(b"::\n\n   ")

        ui.write(b", ".join(d[b'aliases']))

        ui.write(b"\n")

def _splitdoc(obj):

    objdoc = pycompat.getdoc(obj)

    firstnl = objdoc.find(b'\n')

    if firstnl > 0:

        shortdoc = objdoc[:firstnl]

        longdoc = objdoc[firstnl + 1 :]

    else:

        shortdoc = objdoc

        longdoc = ''

    return shortdoc.lstrip(), longdoc.lstrip()

def _rendertpl(tplname, data):

    tplpath = os.path.join(os.path.dirname(__file__), 'templates', tplname)

    with open(tplpath) as f:

        tpl = f.read()

    if isinstance(tpl, bytes):

        tpl = tpl.decode()

    for k in data:

        data[k] = data[k].decode()

    return tpl % data

def gettopicstable():

    extrahelptable = [

        ([b"common"], b'', loaddoc(b'common'), help.TOPIC_CATEGORY_MISC),

        ([b"hg.1"], b'', loaddoc(b'hg.1'), help.TOPIC_CATEGORY_CONFIG),

        ([b"hg-ssh.8"], b'', loaddoc(b'hg-ssh.8'), help.TOPIC_CATEGORY_CONFIG),

        (

            [b"hgignore.5"],

            b'',

            loaddoc(b'hgignore.5'),

            help.TOPIC_CATEGORY_CONFIG,

        ),

        ([b"hgrc.5"], b'', loaddoc(b'hgrc.5'), help.TOPIC_CATEGORY_CONFIG),

        ([b"hg-ssh.8.gendoc"], b'', b'', help.TOPIC_CATEGORY_CONFIG),

        (

            [b"hgignore.5.gendoc"],

            b'',

            loaddoc(b'hgignore'),

            help.TOPIC_CATEGORY_CONFIG,

        ),

        (

            [b"hgrc.5.gendoc"],

            b'',

            loaddoc(b'config'),

            help.TOPIC_CATEGORY_CONFIG,

        ),

    ]

    return helptable + extrahelptable

def findtopics(helptable, include=[], exclude=[]):

    """Find topics whose names match the given include/exclude rules

    Note that exclude rules take precedence over include rules.

    """

    found = []

    for h in helptable:

        names, sec, doc = h[0:3]

        if exclude and names[0] in exclude:

            continue

        if include and names[0] not in include:

            continue

        found.append((names, sec, doc))

    return found

def showtopic(ui, topic, wraptpl=False):

    """Render a help topic

    Args:

        ui: the UI object to output to

        topic: the topic name to output

        wraptpl: whether to wrap the output in the individual help topic

            pages' header/footer

    """

    found = findtopics(gettopicstable(), include=[topic])

    if not found:

        ui.write_err(_(b"ERROR: no such topic: %s\n") % topic)

        sys.exit(1)

    if wraptpl:

        header = _rendertpl(

            'topicheader.txt',

            {'topicname': topic, 'topictitle': minirst.section(found[0][1])},

        )

        ui.write(header.encode())

    helpprinter(ui, found, None)

    return True

def helpprinter(ui, topics, sectionfunc):

    """Print a help topic

    Args:

        ui: the UI object to output to

        topics: a list of help topics to output

        sectionfunc: a callback to write the section title

    """

    for h in topics:

        names, sec, doc = h[0:3]

        for name in names:

            ui.write(b".. _%s:\n" % name)

        ui.write(b"\n")

        if sectionfunc:

            ui.write(sectionfunc(sec))

        if callable(doc):

            doc = doc(ui)

        ui.write(doc)

        ui.write(b"\n")

def showextension(ui, extensionname, debugcmds=False):

    """Render the help text for an extension

    Args:

        ui: the UI object to output to

        extensionname: the name of the extension to output

        debugcmds: whether to include the extension's debug commands, if any

    """

    mod = extensions.load(ui, extensionname, None)

    header = _rendertpl(

        'extheader.txt',

        {'extname': extensionname, 'exttitle': minirst.section(extensionname)},

    )

    ui.write(header.encode())

    shortdoc, longdoc = _splitdoc(mod)

    if shortdoc:

        ui.write(b"%s\n\n" % gettext(shortdoc))

    if longdoc:

        ui.write(minirst.subsection(_(b"Description")))

        ui.write(b"%s\n\n" % gettext(longdoc))

    cmdtable = getattr(mod, 'cmdtable', None)

    if cmdtable: