\documentclass[12pt, a4paper]{article}
\usepackage[T1]{fontenc}
\usepackage[utf8]{inputenc}
\usepackage[english]{babel}
\usepackage{mathpazo}
\usepackage{pyjupyter}
\usepackage[hidelinks]{hyperref}
\usepackage{geometry}
\geometry{left=2cm, right=2cm, top=2cm, bottom=2cm}
\usepackage{parskip}

\title{The \texttt{pyjupyter} package}
\author{Bright Bara\\ \href{mailto:barabright62@gmail.com}{barabright62@gmail.com}}
\date{\today}

\begin{document}
    
    \maketitle
    
    \section{Introduction}
    
    The \texttt{pyjupyter} package provides a lightweight environment for
    typesetting Python code in \LaTeX{} documents.
    
    It combines the functionality of the \texttt{listings} package for
    syntax highlighting with the visual capabilities of \texttt{tcolorbox}
    to produce structured and readable code blocks.
    
    The goal of the package is to provide a simple and robust solution
    for including Python code in :
    
    \begin{itemize}
        \item scientific and technical reports
        \item programming assignments
        \item lecture notes
        \item computational and reproducible research documents
    \end{itemize}
    
    The visual style is inspired by Jupyter notebooks while remaining
    minimal and fully compatible with standard \LaTeX\ workflows.
    
    \section{Basic usage}
    
    Load the package in the document preamble :
    
    \begin{verbatim}
\usepackage{pyjupyter}
    \end{verbatim}
    
    The package defines a single environment called \texttt{jupyter}.
    
    \subsection*{Example}
    
\begin{jupyter}[]
# Example Python code
def square(x):
    return x ** 2

print(square(4))
    \end{jupyter}
    
    \section{Important notes}
    
    \subsection{About the brackets}
    
    The \texttt{jupyter} environment must always be invoked with brackets immediately
    after\\ \verb|\begin{jupyter}| :
    \vspace*{0.5cm}
        
    \begin{verbatim}
    \begin{jupyter}[]
        ...
    \end{jupyter}
    \end{verbatim}
        
    This applies even when no options are specified.
    
    The reason for this is that Python comments start with the character \texttt{\#}.  
    In \TeX\, the character \texttt{\#} is also used internally to denote macro parameters.
    
    If the environment is started without the optional argument brackets
    and the first line of code begins with a Python comment, \TeX{} may
    interpret the character incorrectly during argument parsing.
    
    Providing the optional brackets ensures that the environment is fully
    initialized before the code content is processed by the
    \texttt{listings} engine. This prevents compilation errors when the
    first line of the code block is a Python comment.
    
    \subsection{About highlighting of operators and spaces}
    
    The current version of \texttt{pyjupyter} relies on the \texttt{listings} 
    engine for syntax highlighting. Due to the way this engine parses 
    characters, mathematical and logical operators (such as \texttt{+}, 
    \texttt{-}, \texttt{=}, \texttt{*}, etc.) are highlighted in 
    \textbf{violet} only when they are surrounded by spaces.
    
    If the code is written in a compact way (e.g., \texttt{x=5+2}), the 
    operators will remain in the default text color (black).
    
    \begin{itemize}
        \item \textbf{Correct highlighting} : \texttt{x = 5 + 2}
        \item \textbf{No highlighting} : \texttt{x=5+2}
    \end{itemize}
    
    While this is a technical limitation of the underlying engine, it 
    also promotes the \textbf{PEP 8} style guidelines, which recommend 
    surrounding operators with spaces for better readability.
    
    \vspace*{0.5cm}
    
    \begin{jupyter}[]
# Operators are highlighted with spaces:
a = 10
b = 5
result = a + b

# Operators remain black without spaces:
result=a+b
    \end{jupyter}
    
    
    \newpage
    \section{Line numbering}
    
    The package provides a convenient option called \texttt{numbered}
    to enable line numbering.
    
    \begin{jupyter}[numbered]
'''
Example with line numbers
'''
for i in range(5):
    print(i)
    \end{jupyter}
    
    Using the \texttt{numbered} option is the recommended way to activate
    line numbers.
    
    It internally configures the underlying \texttt{listings} settings
    to produce consistent numbering.
    
    \section{Customization}
    
    \subsection{Passing options to \texttt{tcolorbox}}
    
    The \texttt{jupyter} environment accepts any option supported by
    \texttt{tcolorbox} :
    
    \begin{verbatim}
\begin{jupyter}[title=\textbf{Code}, colframe=Navy, colback=blue!2]
    print("Custom background color")
\end{jupyter}
    \end{verbatim}
    \begin{jupyter}[title=\textbf{Code}, colframe=Navy, colback=blue!2]
print("Custom background color")
    \end{jupyter}
    
    \subsection{Passing options to \texttt{listings}}
    
    Advanced users may still pass options directly to the \texttt{listings}
    engine using the \texttt{listing options} key.
    
    \begin{verbatim}
    \begin{jupyter}[listing options={basicstyle=\ttfamily\small}]
        print("Custom listings options")
    \end{jupyter}
    \end{verbatim}
    
    \begin{jupyter}[listing options={basicstyle=\ttfamily\small}]
print("Custom listings options")
    \end{jupyter}
    
    \section{License}
    
    This package is distributed under the
    \textit{LaTeX Project Public License (LPPL)} version 1.3c.
    
    
\end{document}
