Merge pull request #1667 from opentensor/docs/make-clear-pr-rules

ensure branch off from staging and rm old docs

bittensor/axon.py

@@ -59,20 +59,20 @@
 
 class FastAPIThreadedServer(uvicorn.Server):
     """
-    The ``FastAPIThreadedServer`` class is a specialized server implementation for the Axon server in the Bittensor network. 
-    
+    The ``FastAPIThreadedServer`` class is a specialized server implementation for the Axon server in the Bittensor network.
+
     It extends the functionality of :func:`uvicorn.Server` to run the FastAPI application in a separate thread, allowing the Axon server to handle HTTP requests concurrently and non-blocking.
 
     This class is designed to facilitate the integration of FastAPI with the Axon's asynchronous architecture, ensuring efficient and scalable handling of network requests.
 
     Importance and Functionality
         Threaded Execution
-            The class allows the FastAPI application to run in a separate thread, enabling concurrent handling of HTTP requests which is crucial for the performance and scalability of the Axon server.  
+            The class allows the FastAPI application to run in a separate thread, enabling concurrent handling of HTTP requests which is crucial for the performance and scalability of the Axon server.
 
         Seamless Integration
             By running FastAPI in a threaded manner, this class ensures seamless integration of FastAPI's capabilities with the Axon server's asynchronous and multi-threaded architecture.
 
-        Controlled Server Management 
+        Controlled Server Management
             The methods start and stop provide controlled management of the server's lifecycle, ensuring that the server can be started and stopped as needed, which is vital for maintaining the Axon server's reliability and availability.
 
         Signal Handling
@@ -81,7 +81,7 @@ class FastAPIThreadedServer(uvicorn.Server):
     Use Cases
         Starting the Server
             When the Axon server is initialized, it can use this class to start the FastAPI application in a separate thread, enabling it to begin handling HTTP requests immediately.
-            
+
         Stopping the Server
             During shutdown or maintenance of the Axon server, this class can be used to stop the FastAPI application gracefully, ensuring that all resources are properly released.
 
@@ -152,8 +152,8 @@ def stop(self):
 
 class axon:
     """
-    The ``axon`` class in Bittensor is a fundamental component that serves as the server-side interface for a neuron within the Bittensor network. 
-    
+    The ``axon`` class in Bittensor is a fundamental component that serves as the server-side interface for a neuron within the Bittensor network.
+
     This class is responsible for managing
     incoming requests from other neurons and implements various mechanisms to ensure efficient
     and secure network interactions.
@@ -180,7 +180,7 @@ class is designed to be flexible and customizable, allowing users to specify cus
     - Command-line argument support for user-friendly program interaction.
 
     Example Usage::
-    
+
         import bittensor
         # Define your custom synapse class
         class MySyanpse( bittensor.Synapse ):
@@ -428,7 +428,7 @@ def attach(
             priority_fn (Callable, optional): Function to rank requests based on their priority. It should take the same arguments as :func:`forward_fn` and return a numerical value representing the request's priority. Defaults to ``None``, meaning no priority sorting will be applied.
             verify_fn (Callable, optional): Function to verify requests. It should take the same arguments as :func:`forward_fn` and return a boolean value. If ``None``, :func:`self.default_verify` function will be used.
 
-        Note: 
+        Note:
             The methods :func:`forward_fn`, :func:`blacklist_fn`, :func:`priority_fn`, and :func:`verify_fn` should be designed to receive the same parameters.
 
         Raises:
@@ -441,7 +441,7 @@ def attach(
             self: Returns the instance of the AxonServer class for potential method chaining.
 
         Example Usage::
-        
+
             def forward_custom(synapse: MyCustomSynapse) -> MyCustomSynapse:
                 # Custom logic for processing the request
                 return synapse
@@ -679,7 +679,7 @@ async def verify_body_integrity(self, request: Request):
                         The response includes the detailed error message specifying which field has a hash mismatch.
 
         This method performs several key functions:
-        
+
         1. Decoding and loading the request body for inspection.
         2. Gathering required field names for hash comparison from the Axon configuration.
         3. Loading and parsing the request body into a dictionary.
@@ -780,7 +780,7 @@ def start(self) -> "bittensor.axon":
             bittensor.axon: The Axon instance in the 'started' state.
 
         Example::
-        
+
             my_axon = bittensor.axon(...)
             ... # setup axon, attach functions, etc.
             my_axon.start()  # Starts the axon server
@@ -806,12 +806,12 @@ def stop(self) -> "bittensor.axon":
             bittensor.axon: The Axon instance in the 'stopped' state.
 
         Example::
-            
+
             my_axon = bittensor.axon(...)
             my_axon.start()
             ...
             my_axon.stop()  # Stops the axon server
-            
+
 
         Note:
             It is advisable to ensure that all ongoing processes or requests are completed or properly handled before invoking this method.
@@ -837,7 +837,7 @@ def serve(
             bittensor.axon: The Axon instance that is now actively serving on the specified subtensor.
 
         Example::
-            
+
             my_axon = bittensor.axon(...)
             subtensor = bt.subtensor(network="local") # Local by default
             my_axon.serve(netuid=1, subtensor=subtensor)  # Serves the axon on subnet with netuid 1
@@ -962,8 +962,8 @@ def log_and_handle_error(
 
 class AxonMiddleware(BaseHTTPMiddleware):
     """
-    The `AxonMiddleware` class is a key component in the Axon server, responsible for processing all incoming requests. 
-    
+    The `AxonMiddleware` class is a key component in the Axon server, responsible for processing all incoming requests.
+
     It handles the essential tasks of verifying requests, executing blacklist checks,
     running priority functions, and managing the logging of messages and errors. Additionally, the class
     is responsible for updating the headers of the response and executing the requested functions.
@@ -1008,7 +1008,7 @@ async def dispatch(
             Response: The HTTP response generated after processing the request.
 
         This method performs several key functions:
-    
+
         1. Request Preprocessing: Sets up Synapse object from request headers and fills necessary information.
         2. Logging: Logs the start of request processing.
         3. Blacklist Checking: Verifies if the request is blacklisted.
@@ -1120,7 +1120,7 @@ async def preprocess(self, request: Request) -> bittensor.Synapse:
             bittensor.Synapse: The Synapse object representing the preprocessed state of the request.
 
         The preprocessing involves:
-    
+
         1. Extracting the request name from the URL path.
         2. Creating a Synapse instance from the request headers using the appropriate class type.
         3. Filling in the Axon and Dendrite information into the Synapse object.
@@ -1188,7 +1188,7 @@ async def verify(self, synapse: bittensor.Synapse):
             Exception: If the verification process fails due to unmet criteria or security concerns.
 
         The verification process involves:
-    
+
         1. Retrieving the specific verification function for the request's Synapse type.
         2. Executing the verification function and handling any exceptions that arise.
 
@@ -1236,7 +1236,7 @@ async def blacklist(self, synapse: bittensor.Synapse):
             Exception: If the request is found in the blacklist.
 
         The blacklist check involves:
-        
+
         1. Retrieving the blacklist checking function for the request's Synapse type.
         2. Executing the check and handling the case where the request is blacklisted.
 

bittensor/commands/delegates.py

@@ -54,8 +54,8 @@ def show_delegates(
     width: Optional[int] = None,
 ):
     """
-    Displays a formatted table of Bittensor network delegates with detailed statistics to the console. 
-    
+    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.
 
@@ -67,7 +67,7 @@ def show_delegates(
         - 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.
@@ -86,7 +86,7 @@ def show_delegates(
         options to users who are considering where to stake their tokens.
 
     Example usage::
-    
+
         show_delegates(current_delegates, previous_delegates, width=80)
 
     Note:
@@ -214,8 +214,8 @@ def show_delegates(
 
 class DelegateStakeCommand:
     """
-    Executes the ``delegate`` command, which stakes Tao to a specified delegate on the Bittensor network. 
-    
+    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:
@@ -230,7 +230,7 @@ class DelegateStakeCommand:
         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
 
@@ -343,8 +343,8 @@ 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. 
-    
+    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:
@@ -359,7 +359,7 @@ class DelegateUnstakeCommand:
         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
 
@@ -478,16 +478,16 @@ 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. 
-    
+    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).
@@ -504,7 +504,7 @@ class ListDelegatesCommand:
     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`
@@ -567,12 +567,12 @@ def check_config(config: "bittensor.config"):
 
 class NominateCommand:
     """
-    Executes the ``nominate`` command, which facilitates a wallet to become a delegate on the Bittensor network. 
-    
+    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.
 
@@ -586,7 +586,7 @@ class NominateCommand:
         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
 
@@ -669,8 +669,8 @@ 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. 
-    
+    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.
 
@@ -679,7 +679,7 @@ class MyDelegatesCommand:
         - ``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.
@@ -699,7 +699,7 @@ class MyDelegatesCommand:
         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

bittensor/commands/identity.py

@@ -9,8 +9,8 @@
 
 class SetIdentityCommand:
     """
-    Executes the :func:`set_identity` command within the Bittensor network, which allows for the creation or update of a delegate's on-chain identity. 
-    
+    Executes the :func:`set_identity` command within the Bittensor network, which allows for the creation or update of a delegate's on-chain identity.
+
     This identity includes various
     attributes such as display name, legal name, web URL, PGP fingerprint, and contact
     information, among others.
@@ -250,12 +250,12 @@ class GetIdentityCommand:
         - ``key``: The ``ss58`` address of the coldkey or hotkey to query.
 
     The command performs the following actions:
-    
+
     - Connects to the subtensor network and retrieves the identity information.
     - Displays the information in a structured table format.
 
     The displayed table includes:
-    
+
     - **Address**: The ``ss58`` address of the queried key.
     - **Item**: Various attributes of the identity such as stake, rank, and trust.
     - **Value**: The corresponding values of the attributes.
@@ -265,7 +265,7 @@ class GetIdentityCommand:
         provided in the configuration, the user is prompted to enter one.
 
     Example usage::
-    
+
         btcli wallet get_identity --key <s58_address>
 
     Note:

bittensor/commands/inspect.py

@@ -73,22 +73,22 @@ def _get_hotkey_wallets_for_wallet(wallet) -> List["bittensor.wallet"]:
 
 class InspectCommand:
     """
-    Executes the ``inspect`` command, which compiles and displays a detailed report of a user's wallet pairs (coldkey, hotkey) on the Bittensor network. 
-    
+    Executes the ``inspect`` command, which compiles and displays a detailed report of a user's wallet pairs (coldkey, hotkey) on the Bittensor network.
+
     This report includes balance and
     staking information for both the coldkey and hotkey associated with the wallet.
 
     Optional arguments:
         - ``all``: If set to ``True``, the command will inspect all wallets located within the specified path. If set to ``False``, the command will inspect only the wallet specified by the user.
 
     The command gathers data on:
-    
+
     - Coldkey balance and delegated stakes.
     - Hotkey stake and emissions per neuron on the network.
     - Delegate names and details fetched from the network.
 
     The resulting table includes columns for:
-    
+
     - **Coldkey**: The coldkey associated with the user's wallet.
     - **Balance**: The balance of the coldkey.
     - **Delegate**: The name of the delegate to which the coldkey has staked funds.
@@ -103,7 +103,7 @@ class InspectCommand:
         and performance in the Bittensor network.
 
     Example usage::
-        
+
             btcli wallet inspect
             btcli wallet inspect --all