Click Domain

def setup(app):
    """
    Register Click domain if Click is installed.
    
    Conditionally loads the Click domain functionality only when the
    Click library is available in the environment.
    
    Parameters:
    - app: Sphinx application instance
    """

# RST directive usage:
# .. click:example::
#
#    import click
#    
#    @click.command()
#    @click.option('--name', default='World')
#    def hello(name):
#        click.echo(f'Hello {name}!')

# RST directive usage:
# .. click:run::
#
#    invoke(hello, ['--name', 'Documentation'])
#    println("Custom output line")

class ExampleRunner(CliRunner):
    """
    Click command runner for documentation examples.
    
    Extends Click's CliRunner to capture and format command execution
    for display in Sphinx documentation with proper input/output formatting.
    """
    
    def __init__(self):
        """Initialize runner with Click namespace and stdin echoing."""
        
    def invoke(self, cli, args=None, prog_name=None, input=None, 
               terminate_input=False, env=None, _output_lines=None, **extra):
        """
        Execute Click command with output capture.
        
        Parameters:
        - cli: Click command or group to execute
        - args: List of command arguments
        - prog_name: Program name to display (defaults to cli.name)
        - input: Input to provide to command (string or list of strings)
        - terminate_input: Whether to add EOF marker (^D) after input
        - env: Environment variables to set
        - _output_lines: Internal list for collecting output
        - **extra: Additional CliRunner.invoke arguments
        
        Returns:
        Click Result object with execution details
        """
        
    def declare_example(self, source):
        """
        Execute Python code to define Click commands.
        
        Parameters:
        - source: Python source code string to execute
        """
        
    def run_example(self, source):
        """
        Execute example code and return formatted output lines.
        
        Parameters:
        - source: Python source code containing invoke() calls
        
        Returns:
        list: Lines of formatted input/output for documentation
        """
        
    def close(self):
        """Clean up runner resources."""

class EofEchoingStdin(EchoingStdin):
    """
    Enhanced EchoingStdin that shows EOF as ^D.
    
    Extends Click's EchoingStdin to display a visible '^D' marker
    when EOF character is encountered, improving documentation clarity.
    """

class DeclareExampleDirective(Directive):
    """
    Sphinx directive for declaring Click commands.
    
    Processes Python code content and adds it to the document's
    ExampleRunner namespace for later execution.
    
    Attributes:
    - has_content: True
    - required_arguments: 0
    - optional_arguments: 0
    """
    
class RunExampleDirective(Directive):
    """
    Sphinx directive for executing Click commands.
    
    Runs commands using the document's ExampleRunner and displays
    the formatted input/output in the documentation.
    
    Attributes:
    - has_content: True  
    - required_arguments: 0
    - optional_arguments: 0
    """

class ClickDomain(Domain):
    """
    Sphinx domain for Click documentation.
    
    Provides click:example and click:run directives for interactive
    command-line documentation.
    
    Attributes:
    - name: "click"
    - label: "Click"
    - directives: {"example": DeclareExampleDirective, "run": RunExampleDirective}
    """

.. click:example::

   import click
   
   @click.command()
   @click.option('--count', default=1, help='Number of greetings')
   @click.option('--name', prompt='Your name', help='Person to greet')
   def hello(count, name):
       """Simple program that greets NAME for a total of COUNT times."""
       for _ in range(count):
           click.echo(f'Hello {name}!')

.. click:run::

   invoke(hello, ['--count', '3', '--name', 'Alice'])

.. click:example::

   @click.command()
   @click.option('--interactive', is_flag=True, help='Interactive mode')
   def configure(interactive):
       if interactive:
           name = click.prompt('Enter your name')
           email = click.prompt('Enter your email')
           click.echo(f'Configuration saved for {name} ({email})')
       else:
           click.echo('Non-interactive configuration')

.. click:run::

   invoke(configure, ['--interactive'], input=['John Doe', 'john@example.com'])

.. click:run::

   invoke(hello, ['--name', 'Production'], 
          env={'DEBUG': 'false', 'ENV': 'production'})

.. click:run::

   invoke(hello, ['--help'])
   println()
   println("Now let's run the command:")
   invoke(hello, ['--name', 'Documentation'])

.. click:example::

   @click.group()
   def cli():
       """Main command group."""
       pass
   
   @cli.command()
   def init():
       click.echo('Initializing project...')
   
   @cli.command()
   @click.argument('name')
   def create(name):
       click.echo(f'Creating {name}...')

.. click:run::

   invoke(cli, ['--help'])
   invoke(cli, ['init'])
   invoke(cli, ['create', 'myproject'])

def get_example_runner(document):
    """
    Get or create ExampleRunner for a document.
    
    Parameters:
    - document: Sphinx document object
    
    Returns:
    ExampleRunner: Runner instance associated with the document
    """

def delete_example_runner_state(app, doctree):
    """
    Clean up ExampleRunner after document processing.
    
    Parameters:
    - app: Sphinx application instance
    - doctree: Document tree being processed
    """

def patch_modules():
    """
    Context manager for patching subprocess calls.
    
    Redirects subprocess.call output to click.echo so it appears
    in example output.
    
    Returns:
    ContextManager: Context manager for patched environment
    """