Installation Guide
==================

This comprehensive guide covers all installation methods for {{ project_name }}.

.. contents:: Table of Contents
   :local:
   :depth: 2

System Requirements
-------------------

**Minimum Requirements:**

- **Python**: 3.8 or higher (3.10+ recommended)
- **Operating System**: Windows, macOS, or Linux
- **Package Manager**: pip (included with Python) or poetry

**Recommended Setup:**

- **Python**: 3.11+ for best performance
- **Virtual Environment**: venv, conda, or poetry
- **Git**: For development and contributing

Quick Install
-------------

For most users, the simplest installation method:

.. tab-set::

    .. tab-item:: pip

        .. code-block:: bash

            pip install {{ package_name }}

    .. tab-item:: poetry

        .. code-block:: bash

            poetry add {{ package_name }}

    .. tab-item:: conda

        .. code-block:: bash

            # If available on conda-forge
            conda install -c conda-forge {{ package_name }}

{% if package_name == "pydevelop-docs" %}
Documentation-Specific Installation
-----------------------------------

For documentation projects, you'll want to install with documentation dependencies:

.. code-block:: bash

   # Install with documentation extras
   pip install {{ package_name }}[docs]
   
   # Or add to existing project
   poetry add {{ package_name }} --group docs

This includes all 40+ Sphinx extensions and their dependencies.
{% endif %}

Virtual Environment Setup
--------------------------

**Using venv (Recommended for beginners):**

.. code-block:: bash

   # Create virtual environment
   python -m venv .venv
   
   # Activate (Linux/macOS)
   source .venv/bin/activate
   
   # Activate (Windows)
   .venv\Scripts\activate
   
   # Install package
   pip install {{ package_name }}

**Using poetry (Recommended for projects):**

.. code-block:: bash

   # Initialize new project
   poetry init
   
   # Add dependency
   poetry add {{ package_name }}
   
   # Install and activate shell
   poetry install
   poetry shell

**Using conda:**

.. code-block:: bash

   # Create environment
   conda create -n {{ package_name.replace('-', '_') }} python=3.11
   
   # Activate environment
   conda activate {{ package_name.replace('-', '_') }}
   
   # Install package
   pip install {{ package_name }}

Development Installation
------------------------

For contributing or customizing {{ project_name }}:

.. code-block:: bash

   # Clone repository
   git clone https://github.com/{{ github_org }}/{{ github_repo }}.git
   cd {{ github_repo }}
   
   # Install in development mode
   pip install -e .
   
   # Or with poetry
   poetry install
   
   # Install development dependencies
   pip install -e ".[dev]"  # or poetry install --with dev

{% if package_name == "pydevelop-docs" %}
**For {{ project_name }} Development:**

.. code-block:: bash

   # Clone with all dependencies
   git clone https://github.com/{{ github_org }}/{{ github_repo }}.git
   cd {{ github_repo }}
   
   # Install with all extras
   poetry install --with dev,docs,test
   
   # Run tests to verify
   poetry run pytest
   
   # Build own documentation
   cd docs && poetry run sphinx-build source build
{% endif %}

Platform-Specific Notes
------------------------

**Windows:**

.. code-block:: batch

   # Use PowerShell or Command Prompt
   python -m pip install {{ package_name }}
   
   # If you get permission errors
   python -m pip install --user {{ package_name }}

**macOS:**

.. code-block:: bash

   # If using Homebrew Python
   /opt/homebrew/bin/python3 -m pip install {{ package_name }}
   
   # System Python (not recommended)
   python3 -m pip install --user {{ package_name }}

**Linux:**

.. code-block:: bash

   # Ubuntu/Debian
   sudo apt update && sudo apt install python3-pip
   python3 -m pip install {{ package_name }}
   
   # CentOS/RHEL/Fedora
   sudo dnf install python3-pip
   python3 -m pip install {{ package_name }}

Verify Installation
-------------------

After installation, verify everything is working:

**Check version:**

.. code-block:: bash

   python -c "import {{ package_name.replace('-', '_') }}; print({{ package_name.replace('-', '_') }}.__version__)"

{% if package_name == "pydevelop-docs" %}
**Test CLI:**

.. code-block:: bash

   pydevelop-docs --version
   pydevelop-docs --help

**Quick test:**

.. code-block:: bash

   # Create test directory
   mkdir test-docs && cd test-docs
   
   # Initialize (dry run)
   pydevelop-docs init --dry-run
{% else %}
**Test basic functionality:**

.. code-block:: python

   import {{ package_name.replace('-', '_') }}
   
   # Basic test
   print("{{ project_name }} imported successfully!")
   
   # Check available functions/classes
   print(dir({{ package_name.replace('-', '_') }}))
{% endif %}

Troubleshooting
---------------

**Common Issues:**

.. tab-set::

    .. tab-item:: Permission Errors

        .. code-block:: bash

            # Use --user flag
            pip install --user {{ package_name }}
            
            # Or use virtual environment (recommended)
            python -m venv .venv && source .venv/bin/activate

    .. tab-item:: Import Errors

        .. code-block:: bash

            # Check installation location
            python -c "import {{ package_name.replace('-', '_') }}; print({{ package_name.replace('-', '_') }}.__file__)"
            
            # Reinstall if needed
            pip uninstall {{ package_name }} && pip install {{ package_name }}

    .. tab-item:: Version Conflicts

        .. code-block:: bash

            # Check for conflicts
            pip check
            
            # Upgrade pip first
            python -m pip install --upgrade pip
            
            # Force reinstall
            pip install --force-reinstall {{ package_name }}

{% if package_name == "pydevelop-docs" %}
    .. tab-item:: Missing Extensions

        .. code-block:: bash

            # Install with all extras
            pip install {{ package_name }}[all]
            
            # Or individual extras
            pip install {{ package_name }}[mermaid,graphviz]
{% endif %}

**Getting Help:**

If you're still having issues:

{# djlint:off H025 #}
1. Check the `FAQ <https://github.com/{{ github_org }}/{{ github_repo }}/wiki/FAQ>`_
2. Search `existing issues <https://github.com/{{ github_org }}/{{ github_repo }}/issues>`_
3. Create a `new issue <https://github.com/{{ github_org }}/{{ github_repo }}/issues/new>`_ with:
{# djlint:on #}
   - Your operating system
   - Python version (``python --version``)
   - Complete error message
   - Installation method used

Upgrading
---------

To upgrade to the latest version:

.. code-block:: bash

   # With pip
   pip install --upgrade {{ package_name }}
   
   # With poetry
   poetry update {{ package_name }}
   
   # Check new version
   {{ package_name.replace('-', '_') }} --version

Next Steps
----------

Now that {{ project_name }} is installed:

- 🚀 **Quick Start**: :doc:`quickstart` - Get up and running in 5 minutes
- ⚙️ **Configuration**: :doc:`configuration` - Customize your setup
- 📚 **Tutorials**: :doc:`../tutorials/first_steps` - Detailed walkthrough
- 💡 **Examples**: :doc:`../examples/index` - See real-world usage

.. tip::
   **New to {{ project_name }}?** Start with the :doc:`quickstart` guide for a hands-on introduction!