// Copyright (C) 2023 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only

/*!
    \page creator-copilot.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-edit

    \title Use GitHub Copilot

    The Copilot plugin (disabled by default) integrates
    \l{https://github.com/features/copilot}{GitHub Copilot} into \QC.
    You can view suggestions from Copilot in the \uicontrol Edit mode.

    \note If you enable the Copilot plugin, you must agree with and abide by
    the GitHub terms of use. It is your responsibility to know and accept the
    requirements and parameters of using Copilot, such as ensuring you have
    the rights to grant it access to your code. Also, you must understand the
    implications of using it and the suggestions it produces, such as code
    copyright and accuracy.

    \section1 Requirements

    To use the Copilot plugin, you need:

    \list
        \li An active \l{https://docs.github.com/en/billing/managing-billing-for-github-copilot/about-billing-for-github-copilot}
            {GitHub Copilot subscription}.
        \li GitHub Copilot Neovim plugin installed (requires Node.js), as described in
            \l{https://github.com/github/copilot.vim/blob/release/README.md}
            {Copilot.vim/Readme.md}.
    \endlist

    \section1 Set Copilot preferences

    To set preferences for using Copilot:

    \list 1
        \li Go to \preferences > \uicontrol AI > \uicontrol Copilot.
            \image {qtcreator-preferences-copilot.webp} {Copilot tab in AI preferences}
        \li Select \uicontrol {Enable Copilot} to use Copilot.
        \li Select \uicontrol {Sign In} to sign into your subscription, activate
            your device, and authorize the GitHub Copilot plugin.

            The button turns into a \uicontrol {Sign Out} button.
        \li In \uicontrol {Node.js path}, enter the full path to the
            Node.js executable.
        \li In \uicontrol {Path to language-server.js}, enter the path to
            \c language-server.js in the Copilot Neovim plugin installation folder.
        \li Select \uicontrol {Auto request} to receive suggestions
            for the current text cursor position when you make changes.
        \li In \uicontrol {GitHub Enterprise URL}, enter the URL to Copilot
            server that runs in the enterprise environment.
        \li In \uicontrol {Proxy}, enter the host name and port number of the
            proxy server to connect to Copilot servers.
        \li Select \uicontrol {Reject unauthorized} to prevent the
            security risk presented by accepting unauthorized certificates from
            the proxy server.
    \endlist

    \section1 Receive suggestions

    When you write code in the \l {Editing code}{Edit} mode and
    \uicontrol {Auto request} is enabled, Copilot automatically makes
    suggestions when you type.

    \image {qtcreator-copilot.gif} {Receiving suggestions from Copilot in the editor}

    To manually request a suggestion at the current editor's cursor position,
    enter \uicontrol {t}, followed by \key Space to show
    \uicontrol {Request Copilot Suggestion} in the \l{Navigate with locator}
    {locator}.

    Hover over a suggestion to show a toolbar with \inlineimage {icons/prev.png} {Previous}
    and \inlineimage {icons/next.png} {Next}
    buttons for cycling between Copilot suggestions.

    To apply a suggestion as a whole, select \uicontrol Apply or \key Tab.

    To apply a suggestion word-by-word, select \uicontrol {Apply Word}
    or \key {Alt+Right}.

    To reject a suggestion, select \key Esc or the arrow keys.

    \section1 Turn suggestions on and off

    You can turn the Copilot suggestions on and off either globally for all
    projects or at project level for a particular project.

    \section2 Toggle Copilot suggestions

    To turn Copilot suggestions on or off globally, select
    \inlineimage {icons/copilot.png} {Toggle Copilot} (\uicontrol {Toggle Copilot}).
    This also sets the value of \uicontrol {Enable Copilot} in \preferences >
    \uicontrol Copilot accordingly.

    \section2 Turn suggestions on or off for a project

    To turn Copilot suggestions on or off for a particular project:

    \list 1
        \li Go to \uicontrol Projects > \uicontrol {Project Settings} >
            \uicontrol Copilot.
            \image {qtcreator-project-settings-copilot.webp} {Copilot project settings}
        \li Clear \uicontrol {Use global settings}.
        \li Select or clear \uicontrol {Enable Copilot}.
    \endlist

    \sa {Enable and disable plugins}, {Editing code}
*/
