Adds docstrings for CLI for Sphynx documentation

bittensor/cli.py

@@ -67,6 +67,7 @@
             "weights": RootSetWeightsCommand,
             "get_weights": RootGetWeightsCommand,
             "senate_vote": VoteCommand,
+            "senate": SenateCommand,
             "register": RootRegisterCommand,
             "proposals": ProposalsCommand,
             "delegate": DelegateStakeCommand,

bittensor/commands/__init__.py

@@ -88,7 +88,7 @@
 from .inspect import InspectCommand
 from .metagraph import MetagraphCommand
 from .list import ListCommand
-from .misc import UpdateCommand, ListSubnetsCommand
+from .misc import UpdateCommand
 from .senate import (
     SenateCommand,
     ProposalsCommand,

bittensor/commands/delegates.py

@@ -53,7 +53,51 @@ def show_delegates(
     prev_delegates: Optional[List["bittensor.DelegateInfo"]],
     width: Optional[int] = None,
 ):
-    """Pretty prints a table of delegates sorted by total stake."""
+    """
+    Displays a formatted table of Bittensor network delegates with detailed statistics
+    to the console. The table is sorted by total stake in descending order and provides
+    a snapshot of delegate performance and status, helping users make informed decisions
+    for staking or nominating.
+
+    This is a helper function that is called by the 'list_delegates' and 'my_delegates'
+    and not intended to be used directly in user code unless specifically required.
+
+    Parameters:
+    - delegates (List[bittensor.DelegateInfo]): A list of delegate information objects
+      to be displayed.
+    - prev_delegates (Optional[List[bittensor.DelegateInfo]]): A list of delegate
+      information objects from a previous state, used to calculate changes in stake.
+      Defaults to None.
+    - width (Optional[int]): The width of the console output table. Defaults to None,
+      which will make the table expand to the maximum width of the console.
+
+    The output table includes the following columns:
+    - INDEX: The numerical index of the delegate.
+    - DELEGATE: The name of the delegate.
+    - SS58: The truncated SS58 address of the delegate.
+    - NOMINATORS: The number of nominators supporting the delegate.
+    - DELEGATE STAKE(τ): The stake that is directly delegated to the delegate.
+    - TOTAL STAKE(τ): The total stake held by the delegate, including nominators' stake.
+    - CHANGE/(4h): The percentage change in the delegate's stake over the past 4 hours.
+    - SUBNETS: A list of subnets the delegate is registered with.
+    - VPERMIT: Validator permits held by the delegate for the subnets.
+    - NOMINATOR/(24h)/kτ: The earnings per 1000 τ staked by nominators in the last 24 hours.
+    - DELEGATE/(24h): The earnings of the delegate in the last 24 hours.
+    - Desc: A brief description provided by the delegate.
+
+    Usage:
+    This function is typically used within the Bittensor CLI to show current delegate
+    options to users who are considering where to stake their tokens.
+
+    Example usage:
+    >>> show_delegates(current_delegates, previous_delegates, width=80)
+
+    Note:
+    This function is primarily for display purposes within a command-line interface and does
+    not return any values. It relies on the 'rich' Python library to render the table in the
+    console.
+    """
+
     delegates.sort(key=lambda delegate: delegate.total_stake, reverse=True)
     prev_delegates_dict = {}
     if prev_delegates is not None:
@@ -172,6 +216,36 @@ def show_delegates(
 
 
 class DelegateStakeCommand:
+    """
+    Executes the 'delegate' command, which stakes Tao to a specified delegate on the
+    Bittensor network. This action allocates the user's Tao to support a delegate,
+    potentially earning staking rewards in return.
+
+    Optional Arguments:
+    - wallet.name: The name of the wallet to use for the command.
+    - delegate_ss58key: The SS58 address of the delegate to stake to.
+    - amount: The amount of Tao to stake.
+    - all: If specified, the command stakes all available Tao.
+
+    The command interacts with the user to determine the delegate and the amount of Tao
+    to be staked. If the '--all' flag is used, it delegates the entire available balance.
+
+    Usage:
+    The user must specify the delegate's SS58 address and the amount of Tao to stake. The
+    function sends a transaction to the subtensor network to delegate the specified amount
+    to the chosen delegate. These values are prompted if not provided.
+
+    Example usage:
+    >>> btcli delegate --delegate_ss58key <SS58_ADDRESS> --amount <AMOUNT>
+    >>> btcli delegate --delegate_ss58key <SS58_ADDRESS> --all
+
+    Note:
+    This command modifies the blockchain state and may incur transaction fees. It requires
+    user confirmation and interaction, and is designed to be used within the Bittensor CLI
+    environment. The user should ensure the delegate's address and the amount to be staked
+    are correct before executing the command.
+    """
+
     @staticmethod
     def run(cli):
         """Delegates stake to a chain delegate."""
@@ -269,6 +343,37 @@ def check_config(config: "bittensor.config"):
 
 
 class DelegateUnstakeCommand:
+    """
+    Executes the 'undelegate' command, allowing users to withdraw their staked Tao from
+    a delegate on the Bittensor network. This process is known as "undelegating" and it
+    reverses the delegation process, freeing up the staked tokens.
+
+    Optional Arguments:
+    - wallet.name: The name of the wallet to use for the command.
+    - delegate_ss58key: The SS58 address of the delegate to undelegate from.
+    - amount: The amount of Tao to undelegate.
+    - all: If specified, the command undelegates all staked Tao from the delegate.
+
+    The command prompts the user for the amount of Tao to undelegate and the SS58 address
+    of the delegate from which to undelegate. If the '--all' flag is used, it will attempt
+    to undelegate the entire staked amount from the specified delegate.
+
+    Usage:
+    The user must provide the delegate's SS58 address and the amount of Tao to undelegate.
+    The function will then send a transaction to the Bittensor network to process the
+    undelegation.
+
+    Example usage:
+    >>> btcli undelegate --delegate_ss58key <SS58_ADDRESS> --amount <AMOUNT>
+    >>> btcli undelegate --delegate_ss58key <SS58_ADDRESS> --all
+
+    Note:
+    This command can result in a change to the blockchain state and may incur transaction
+    fees. It is interactive and requires confirmation from the user before proceeding. It
+    should be used with care as undelegating can affect the delegate's total stake and
+    potentially the user's staking rewards.
+    """
+
     @staticmethod
     def run(cli):
         """Undelegates stake from a chain delegate."""
@@ -366,6 +471,43 @@ def check_config(config: "bittensor.config"):
 
 
 class ListDelegatesCommand:
+    """
+    Displays a formatted table of Bittensor network delegates, providing a comprehensive
+    overview of delegate statistics and information. This table helps users make informed
+    decisions on which delegates to allocate their Tao stake.
+
+    Optional Arguments:
+    - wallet.name: The name of the wallet to use for the command.
+    - subtensor.network: The name of the network to use for the command.
+
+    The table columns include:
+    - INDEX: The delegate's index in the sorted list.
+    - DELEGATE: The name of the delegate.
+    - SS58: The delegate's unique SS58 address (truncated for display).
+    - NOMINATORS: The count of nominators backing the delegate.
+    - DELEGATE STAKE(τ): The amount of delegate's own stake (not the TAO delegated from any nominators).
+    - TOTAL STAKE(τ): The delegate's cumulative stake, including self-staked and nominators' stakes.
+    - CHANGE/(4h): The percentage change in the delegate's stake over the last four hours.
+    - SUBNETS: The subnets to which the delegate is registered.
+    - VPERMIT: Indicates the subnets for which the delegate has validator permits.
+    - NOMINATOR/(24h)/kτ: The earnings per 1000 τ staked by nominators in the last 24 hours.
+    - DELEGATE/(24h): The total earnings of the delegate in the last 24 hours.
+    - DESCRIPTION: A brief description of the delegate's purpose and operations.
+
+    Sorting is done based on the 'TOTAL STAKE' column in descending order. Changes in stake
+    are highlighted: increases in green and decreases in red. Entries with no previous data
+    are marked with 'NA'. Each delegate's name is a hyperlink to their respective URL, if available.
+
+    Example usage:
+    >>> btcli root list_delegates
+    >>> btcli root list_delegates --wallet.name my_wallet
+    >>> btcli root list_delegates --subtensor.network finney # can also be `test` or `local`
+
+    Note:
+    This function is part of the Bittensor CLI tools and is intended for use within a console
+    application. It prints directly to the console and does not return any value.
+    """
+
     @staticmethod
     def run(cli):
         r"""
@@ -405,6 +547,36 @@ def check_config(config: "bittensor.config"):
 
 
 class NominateCommand:
+    """
+    Executes the 'nominate' command, which facilitates a wallet to become a delegate
+    on the Bittensor network. This command handles the nomination process, including
+    wallet unlocking and verification of the hotkey's current delegate status.
+
+    The command performs several checks:
+    - Verifies that the hotkey is not already a delegate to prevent redundant nominations.
+    - Tries to nominate the wallet and reports success or failure.
+
+    Upon success, the wallet's hotkey is registered as a delegate on the network.
+
+    Optional Arguments:
+    - wallet.name: The name of the wallet to use for the command.
+    - wallet.hotkey: The name of the hotkey to use for the command.
+
+    Usage:
+    To run the command, the user must have a configured wallet with both hotkey and
+    coldkey. If the wallet is not already nominated, this command will initiate the
+    process.
+
+    Example usage:
+    >>> btcli root nominate
+    >>> btcli root nominate --wallet.name my_wallet --wallet.hotkey my_hotkey
+
+    Note:
+    This function is intended to be used as a CLI command. It prints the outcome directly
+    to the console and does not return any value. It should not be called programmatically
+    in user code due to its interactive nature and side effects on the network state.
+    """
+
     @staticmethod
     def run(cli):
         r"""Nominate wallet."""
@@ -467,6 +639,47 @@ def check_config(config: "bittensor.config"):
 
 
 class MyDelegatesCommand:
+    """
+    Executes the 'my_delegates' command within the Bittensor CLI, which retrieves and
+    displays a table of delegated stakes from a user's wallet(s) to various delegates
+    on the Bittensor network. The command provides detailed insights into the user's
+    staking activities and the performance of their chosen delegates.
+
+    Optional Arguments:
+    - wallet.name: The name of the wallet to use for the command.
+    - all: If specified, the command aggregates information across all wallets.
+
+    The table output includes the following columns:
+    - Wallet: The name of the user's wallet.
+    - OWNER: The name of the delegate's owner.
+    - SS58: The truncated SS58 address of the delegate.
+    - Delegation: The amount of Tao staked by the user to the delegate.
+    - τ/24h: The earnings from the delegate to the user over the past 24 hours.
+    - NOMS: The number of nominators for the delegate.
+    - OWNER STAKE(τ): The stake amount owned by the delegate.
+    - TOTAL STAKE(τ): The total stake amount held by the delegate.
+    - SUBNETS: The list of subnets the delegate is a part of.
+    - VPERMIT: Validator permits held by the delegate for various subnets.
+    - 24h/kτ: Earnings per 1000 Tao staked over the last 24 hours.
+    - Desc: A description of the delegate.
+
+    The command also sums and prints the total amount of Tao delegated across all wallets.
+
+    Usage:
+    The command can be run as part of the Bittensor CLI suite of tools and requires
+    no parameters if a single wallet is used. If multiple wallets are present, the
+    --all flag can be specified to aggregate information across all wallets.
+
+    Example usage:
+    >>> btcli my_delegates
+    >>> btcli my_delegates --all
+    >>> btcli my_delegates --wallet.name my_wallet
+
+    Note:
+    This function is typically called by the CLI parser and is not intended to be used
+    directly in user code.
+    """
+
     @staticmethod
     def run(cli):
         """Delegates stake to a chain delegate."""
@@ -625,6 +838,34 @@ def check_config(config: "bittensor.config"):
 
 
 class SetDelegateTakeCommand:
+    """
+    Executes the 'set_delegate_take' command, which sets the commission rate (take percentage)
+    for a user's delegate on the Bittensor network. This commission is the fraction of rewards
+    that the delegate takes from staking operations.
+
+    Optional Arguments:
+    - wallet.name: The name of the wallet to use for the command.
+    - delegate.take: The take percentage to set for the delegate.
+
+    The function performs several checks:
+    - Ensures the take value is within the valid range (0.0 to 1.0).
+    - Verifies that the hotkey associated with the wallet is registered as a delegate.
+    - Sets the take percentage on the network if the above conditions are met.
+
+    Usage:
+    The user is prompted to enter the desired take value, which must be a float between 0 and 1.
+    The value is then scaled and cast to an integer ratio before being sent to the network.
+
+    Example usage:
+    >>> btcli root set_delegate_take --take 0.1
+    >>> btcli root set_delegate_take --wallet.name my_wallet --wallet.hotkey my_hotkey --take 0.1
+
+    Note:
+    This command will result in a change to the blockchain state and may incur transaction fees.
+    It is interactive and requires input from the user. This function is intended to be used as
+    part of the Bittensor CLI and not as a standalone function within user code.
+    """
+
     @staticmethod
     def run(cli):
         r"""Set your delegate's take percentage."""
@@ -673,7 +914,7 @@ def add_args(parser: argparse.ArgumentParser):
             "set_delegate_take", help="""Set your delegate's take percentage."""
         )
         set_delegate_take_parser.add_argument(
-            "--delegate.take", dest="take", type=str, required=False
+            "--take", dest="take", type=str, required=False
         )
 
         bittensor.wallet.add_args(set_delegate_take_parser)
@@ -689,6 +930,6 @@ def check_config(config: "bittensor.config"):
             hotkey = Prompt.ask("Enter hotkey name", default=defaults.wallet.hotkey)
             config.wallet.hotkey = str(hotkey)
 
-        if not config.is_set("delegate.take") and not config.no_prompt:
+        if not config.is_set("take") and not config.no_prompt:
             take = Prompt.ask("Enter new delegate take value (0 - 1)")
             config.take = take