{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**NOTE**: This tutorial was auto generated using the QWEN 3.6 Large Language Model\n",
    "\n",
    "# Library Configuration\n",
    "\n",
    "pydocmaker provides a set of configuration functions to control output rendering, PDF generation engines, LaTeX compilers, and LibreOffice paths. All configuration functions follow a consistent `config_<feature>_get()` and `config_<feature>_set()` pattern.\n",
    "\n",
    "You can also access them via the `pyd.options` convenience class, e.g. `pyd.options.pdf_engine_get()`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "2.6.9\n"
     ]
    }
   ],
   "source": [
    "import pydocmaker as pyd\n",
    "print(pyd.__version__)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Renderer Configuration\n",
    "\n",
    "The renderer controls how reports are displayed inline within Python (e.g. in Jupyter notebooks). The available options are:\n",
    "\n",
    "| Option  | Description                                       |\n",
    "|---------|---------------------------------------------------|\n",
    "| `auto`  | Automatically chosen based on environment (default)|\n",
    "| `rich`  | Use the Rich library for styled Console output    |\n",
    "| `md`    | Markdown-formatted output                         |\n",
    "| `html`  | HTML-formatted output                             |\n",
    "| `pdf`   | Render as PDF                                     |\n",
    "\n",
    "### Getting the current renderer"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'auto'"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "pyd.config_renderer_default_get()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Changing the renderer"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'rich'"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "pyd.config_renderer_default_set('rich')\n",
    "pyd.config_renderer_default_get()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The function returns the selected renderer, and raising a `ValueError` if an invalid option is passed."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## PDF Engine Configuration\n",
    "\n",
    "pydocmaker supports multiple backends for generating PDF documents. The available PDF engines are:\n",
    "\n",
    "| Engine           | Description                                          |\n",
    "|------------------|------------------------------------------------------|\n",
    "| `typst`          | Typst typesetting system (default)                    |\n",
    "| `tex`            | LaTeX via pdflatex/lualatex/xelatex                   |\n",
    "| `word`           | Microsoft Word via COM automation (Windows only)      |\n",
    "| `libreoffice`    | LibreOffice headless conversion                       |\n",
    "| `pandoc`         | Pandoc document converter                             |\n",
    "\n",
    "### Getting the current PDF engine\n",
    "\n",
    "If no engine has been explicitly set, calling `config_pdf_engine_get()` will trigger auto-detection to find the first available engine on your system:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'typst'"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "pyd.config_pdf_engine_get()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Scanning for available engines\n",
    "\n",
    "You can scan the system to see which PDF engines are actually installed and available:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "['typst', 'tex', 'word', 'libreoffice', 'pandoc']"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Return list of all available engines\n",
    "pyd.config_pdf_engine_scan()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'typst'"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Return only the first available engine\n",
    "pyd.config_pdf_engine_scan(firstonly=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Setting the PDF engine explicitly\n",
    "\n",
    "If you know which engine you want to use, set it directly:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'typst'"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "pyd.config_pdf_engine_set('typst')\n",
    "pyd.config_pdf_engine_get()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Testing engine availability\n",
    "\n",
    "You can test whether the currently configured PDF engine is actually available on your system. By default, it raises a `ValueError` if no valid compiler is found:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Test passed: True\n"
     ]
    }
   ],
   "source": [
    "try:\n",
    "    result = pyd.config_pdf_engine_test(raise_on_error=True)\n",
    "    print(f\"Test passed: {result}\")\n",
    "except ValueError as e:\n",
    "    print(f\"No valid PDF engine found: {e}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "With `raise_on_error=False`, it simply returns `True` or `False`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "pyd.config_pdf_engine_test(raise_on_error=False)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## LaTeX Compiler Configuration\n",
    "\n",
    "When using the `tex` PDF engine, pydocmaker needs a LaTeX compiler. The supported compilers are:\n",
    "\n",
    "| Compiler     | Description                    |\n",
    "|--------------|--------------------------------|\n",
    "| `pdflatex`   | Standard PDFLaTeX              |\n",
    "| `lualatex`   | LuaLaTeX (Lua support)         |\n",
    "| `xelatex`    | XeLaTeX (Unicode/font support) |\n",
    "\n",
    "### Getting the current compiler"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'pdflatex'"
      ]
     },
     "execution_count": 10,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "pyd.config_latex_compiler_get()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If no compiler has been set, this triggers auto-detection to find the first available one.\n",
    "\n",
    "### Scanning for available compilers"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "['pdflatex', 'lualatex', 'xelatex']"
      ]
     },
     "execution_count": 11,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "pyd.config_latex_compiler_scan()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Setting the compiler explicitly\n",
    "\n",
    "You can force a specific compiler (it must be installed on your system):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'xelatex'"
      ]
     },
     "execution_count": 12,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "pyd.config_latex_compiler_set('xelatex')\n",
    "pyd.config_latex_compiler_get()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## LibreOffice Path Configuration\n",
    "\n",
    "When using the `libreoffice` PDF engine, pydocmaker needs to locate the LibreOffice executable. These functions help you manage that path.\n",
    "\n",
    "### Finding the LibreOffice path"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'C:\\\\Program Files\\\\LibreOffice\\\\program\\\\soffice.exe'"
      ]
     },
     "execution_count": 13,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "pyd.config_libreoffice_path_find()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Getting the current path"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'C:\\\\Program Files\\\\LibreOffice\\\\program\\\\soffice.exe'"
      ]
     },
     "execution_count": 14,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "pyd.config_libreoffice_path_get()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Setting a custom path\n",
    "\n",
    "If LibreOffice is installed in a non-standard location, you can set it explicitly:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [],
   "source": [
    "# pyd.config_libreoffice_path_set(r'C:\\Program Files\\LibreOffice\\program\\soffice.exe')\n",
    "# pyd.config_libreoffice_path_get()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Passing `None` forces pydocmaker to re-resolve the path on the next call."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Convenience Functions\n",
    "\n",
    "### pyd.options class\n",
    "\n",
    "For a cleaner namespace, you can access all config functions through the `pyd.options` class:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'rich'"
      ]
     },
     "execution_count": 16,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "pyd.options.pdf_engine_get()\n",
    "pyd.options.pdf_engine_set('typst')\n",
    "pyd.options.latex_compiler_get()\n",
    "pyd.options.renderer_default_get()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### pyd.info_optionals()\n",
    "\n",
    "Get a comprehensive overview of all optional dependencies and their status in one call:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'can_run_pandoc': True,\n",
       " 'can_use_w32_word': True,\n",
       " 'can_use_libreoffice': True,\n",
       " 'pdf_engines_available': ['typst', 'tex', 'word', 'libreoffice', 'pandoc'],\n",
       " 'pdf_engine': 'typst',\n",
       " 'libreoffice_path': 'C:\\\\Program Files\\\\LibreOffice\\\\program\\\\soffice.exe',\n",
       " 'typst_installed': True}"
      ]
     },
     "execution_count": 17,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "pyd.info_optionals()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This returns a dictionary with:\n",
    "\n",
    "| Key                    | Description                              |\n",
    "|------------------------|------------------------------------------|\n",
    "| `can_run_pandoc`       | Whether pandoc is available              |\n",
    "| `can_use_w32_word`     | Whether Word COM automation works (Windows) |\n",
    "| `can_use_libreoffice`  | Whether LibreOffice is available          |\n",
    "| `pdf_engines_available`| List of all available PDF engines         |\n",
    "| `pdf_engine`           | Currently selected PDF engine             |\n",
    "| `libreoffice_path`     | Path to LibreOffice executable            |\n",
    "| `typst_installed`      | Whether Typst is installed               |"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Working Example\n",
    "\n",
    "Here is a complete example showing how to configure pydocmaker for PDF output. First check what engines are available, then set your preferred engine:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Available PDF engines: ['typst', 'tex', 'word', 'libreoffice', 'pandoc']\n",
      "Selected Typst as PDF engine.\n"
     ]
    }
   ],
   "source": [
    "# Check available engines\n",
    "available = pyd.config_pdf_engine_scan()\n",
    "print(f\"Available PDF engines: {available}\")\n",
    "\n",
    "# Set your preferred engine\n",
    "if 'typst' in available:\n",
    "    pyd.config_pdf_engine_set('typst')\n",
    "    print(\"Selected Typst as PDF engine.\")\n",
    "elif 'tex' in available:\n",
    "    pyd.config_pdf_engine_set('tex')\n",
    "    print(\"Selected LaTeX as PDF engine.\")\n",
    "elif 'pandoc' in available:\n",
    "    pyd.config_pdf_engine_set('pandoc')\n",
    "    print(\"Selected Pandoc as PDF engine.\")\n",
    "else:\n",
    "    pyd.config_pdf_engine_test(raise_on_error=True)\n",
    "    print(\"Auto-detected a PDF engine.\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Pandoc Configuration\n",
    "\n",
    "When using pandoc, you can control which pandoc executables are considered allowed:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": 19,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "pyd.config_pandoc_allowed_get()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {},
   "outputs": [],
   "source": [
    "# pyd.config_pandoc_allowed_set(['pandoc', 'pandoc-lua'])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The helper functions `pyd.pandoc_set_enabled()` and `pyd.pandoc_set_disabled()` provide a quick way to allow or disallow pandoc as a conversion option."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "pyd",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.8.19"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}