\documentclass[12pt,a4paper]{article}
\usepackage[T1]{fontenc}
\usepackage[utf8]{inputenc}
\usepackage[english]{babel}
\usepackage{mathpazo}
\usepackage[colorlinks]{hyperref}
\usepackage{url}
\usepackage{geometry}
\geometry{margin=2.5cm}
\usepackage{parskip}
\usepackage{pyjupyter}

\title{The \texttt{pyjupyter} package\\[0.25cm]\large  Version: 1.2.0 - 15/03/2026}
\author{BARA Ouyèté Bright\\ \hypersetup{hidelinks}\href{mailto:barabright62@gmail.com}{\ttfamily barabright62@gmail.com}}
\date{\today}



\begin{document}
    
\maketitle

\renewcommand{\contentsname}{\bfseries\Large Contents\\[-0.6cm]\hrule}
{\hypersetup{hidelinks}\tableofcontents \vspace*{0.25cm}\hrule}


\section{Introduction}

The \texttt{pyjupyter} package provides a lightweight environment
for typesetting Python code in \LaTeX\ documents with a visual style
inspired by Jupyter notebooks.

The package combines the syntax highlighting capabilities of
\texttt{listings} with the layout and framing features of
\texttt{tcolorbox}. The result is a structured and readable
presentation of Python code blocks suitable for:

\begin{itemize}
    \item scientific reports
    \item programming assignments
    \item lecture notes
    \item reproducible research documents
\end{itemize}

A key motivation for this package is to provide a clean alternative to
standard Jupyter-to-\LaTeX\ conversions. Typical conversion tools
generate extremely verbose code, rely on heavy \texttt{Pygments}
dependencies, and clutter the preamble with numerous \texttt{renewcommand}
definitions, making the source file difficult to read and maintain.
\texttt{pyjupyter} avoids this complexity by offering a native,
minimalist approach that remains fully compatible with standard
\LaTeX\ workflows.

 It is important to note that \textbf{the purpose of this package is purely
 typographical}: \texttt{pyjupyter} does not execute or compile Python
 code. Its goal is solely to provide a clean and convenient way to
 display Python source code inside \LaTeX\ documents.

\section{Installation}

If you are using a modern \LaTeX\ distribution (such as \TeX\ Live or MiKTeX),
the package can be installed automatically through your package manager.

Alternatively, you can manually install the package by following these steps:

\begin{enumerate}
    \item Download the package from: {\hypersetup{colorlinks, urlcolor=blue}\url{https://mirrors.ctan.org/macros/latex/contrib/pyjupyter}}\\
    \item Place the file \verb|pyjupyter.sty| in the working directory of your
    project or in your local \texttt{texmf} tree.\\
    \item Run \texttt{texhash} (if necessary) to update your database.
\end{enumerate}


\section{Loading the package}

Load the package in the preamble:\\
    
\begin{lstlisting}[language=TeX, basicstyle=\ttfamily\small, frame=single]
\usepackage{pyjupyter}
\end{lstlisting}
    
The package automatically loads the required dependencies.

\section{The \texttt{jupyter} environment}

The package defines a single environment called \texttt{jupyter}.\\
    
\begin{lstlisting}[language=TeX, basicstyle=\ttfamily\small, frame=single]
\begin{jupyter}[]
# Python code
print("Hello")
\end{jupyter}
\end{lstlisting}
    
\subsection*{Example}
    
\begin{jupyter}[]
# Example Python code
def square(x):
    return x ** 2

print(square(4))
\end{jupyter}
    
    The environment produces a framed code block with Python syntax
    highlighting.
    
    \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{lstlisting}[language=TeX, basicstyle=\ttfamily\small, frame=single]
\begin{jupyter}[]
    ...
\end{jupyter}
\end{lstlisting}

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.
        

\begin{jupyter}[numbered]
# Operators are highlighted with spaces:
a = 10
b = 5
result =  a + b
# Operators remain black without spaces:
result=a+b
\end{jupyter}
        
\section{Line numbering}

Line numbering can be activated using the \texttt{numbered} option.\\

\begin{lstlisting}[language=TeX, basicstyle=\ttfamily\small, frame=single]
\begin{jupyter}[numbered]
for i in range(5):
    print(i)
\end{jupyter}
\end{lstlisting}

\begin{jupyter}[numbered]
for i in range(5):
    print(i)
\end{jupyter}

The option internally configures the settings of the
\texttt{listings} engine.


\section{Font and Size Configuration}

By default, \texttt{pyjupyter} uses the \texttt{sourcecodepro} family at \texttt{small} size. These settings can be customized globally through package options to suit your document's aesthetic.

\subsection{Font Families}
You can globally customize the font for all your Jupyter blocks by passing the \texttt{font} option when loading the package. The following families are supported:

\newpage

\begin{itemize}
    \item \texttt{sourcecodepro} (default)
    \item \texttt{inconsolata}
    \item \texttt{beramono}
    \item \texttt{lmtt}
    \item \texttt{courier}
    \item \texttt{txtt}
\end{itemize}

\subsection{Code Size}
For the code size, you can specify the \LaTeX\ font size command \textbf{without the backslash}.
The most common values are:

\begin{itemize}
    \item \texttt{tiny}, \texttt{scriptsize} or \texttt{footnotesize}
    \item \texttt{small} (default)
    \item \texttt{normalsize}
\end{itemize}

\textit{Note: While larger options like \texttt{large}, \texttt{Large}, or \texttt{LARGE} are technically supported, they are generally not recommended for code listings.}

\subsection{Usage Example}

To use \texttt{inconsolata} with a smaller font size (\texttt{footnotesize}) throughout your entire document, write this in the preamble:\\

\begin{lstlisting}[language=TeX, basicstyle=\ttfamily\small, frame=single]
\usepackage[font=inconsolata, codesize=footnotesize]{pyjupyter}
\end{lstlisting}


\section{Customization}

\subsection{Passing options to \texttt{tcolorbox}}

The \texttt{jupyter} environment allows further customization by
passing options to the underlying \texttt{tcolorbox} environment.\\

\begin{lstlisting}[language=TeX, basicstyle=\ttfamily\small, frame=single]
\begin{jupyter}[colback=blue!3,colframe=Navy,title=Example]
print("Custom box")
\end{jupyter}
\end{lstlisting}

\begin{jupyter}[colback=blue!3,colframe=Navy,title=Example]
print("Custom box")
\end{jupyter}

\subsection{Passing options to \texttt{listings}}

Advanced users may pass options directly to the \texttt{listings}
engine using the key \texttt{listing options}.\\

\begin{lstlisting}[language=TeX, basicstyle=\ttfamily\small, frame=single]
\begin{jupyter}[listing options={basicstyle=\ttfamily\small}]
print("Custom listings configuration")
\end{jupyter}
\end{lstlisting}

\begin{jupyter}[listing options={basicstyle=\ttfamily\small}]
print("Custom listings configuration")
\end{jupyter}

\section{Embedding \LaTeX\ code}

It is possible to insert \LaTeX\ code inside a code block using the
escape delimiters defined in the listings configuration.

The escape characters are two @:

\begin{verbatim}
    @ ... @
\end{verbatim}

Everything between @ delimiters is processed as normal \LaTeX\ code.

Example:

\begin{lstlisting}[language=TeX, basicstyle=\ttfamily\small, frame=single]
\begin{jupyter}[]
x = 10
y = 20
print(x+y) @\hspace*{3cm}\color{orange}$\alpha$ Result@
\end{jupyter}
\end{lstlisting}

\begin{jupyter}[]
x = 10
y = 20
print(x+y)  @\hspace*{3cm}\color{orange}$\alpha$ Result@
\end{jupyter}

This feature allows the user to manually emphasize elements such as function or method names when they are not automatically detected by the syntax highlighting engine.

\section{Including Python files}

The package provides a dedicated command \verb|\inputpythonfile| for including external Python files into your \LaTeX\ document.

This command wraps the file in a \texttt{tcolorbox} with the same Jupyter-style formatting as the \texttt{jupyter} environment, and fully supports syntax highlighting, line numbering, and font customization.

\subsection*{Basic usage}

\begin{lstlisting}[language=TeX, basicstyle=\ttfamily\small, frame=single]
\inputpythonfile{example.py}
\end{lstlisting}

This will include the entire Python file with default styling.

\subsection*{Line numbering}

To enable line numbers inside the included file, pass the \texttt{numbered} option:\\

\begin{lstlisting}[language=TeX, basicstyle=\ttfamily\small, frame=single]
\inputpythonfile[numbered]{example.py}
\end{lstlisting}

\subsection*{Selecting specific lines}

You can include only a specific range of lines using the \texttt{startline} and \texttt{endline} options:

\begin{lstlisting}[language=TeX, basicstyle=\ttfamily\small, frame=single]
\inputpythonfile[numbered, startline=5, endline=10]{example.py}
\end{lstlisting}

This is useful to show only relevant portions of a long Python file.

\subsection*{Custom box options}

You can also customize the \texttt{tcolorbox} appearance by passing standard box options:

\begin{lstlisting}[language=TeX,basicstyle=\ttfamily\scriptsize, frame=single]
\inputpythonfile[title=Included Python code, colframe=Navy, colback=blue!2]{example.py}
\end{lstlisting}

\inputpythonfile[numbered, title=Included Python code, colframe=Navy, colback=blue!2]{example.py}

This approach allows you to display Python files in a clean, readable format while controlling which lines are shown, preserving syntax highlighting, line numbering, and font style from the global \texttt{pyjupyter} configuration.


\section{Syntax highlighting}

Python syntax highlighting is provided by the \texttt{listings}
engine. The package defines a custom style called
\texttt{pyjupyter-syntax}.

The style includes:

\begin{itemize}
    \item highlighting of Python keywords
    \item highlighting of operators
    \item colored comments
    \item colored strings
    \item support for triple-quoted strings
    \item automatic line breaking
\end{itemize}

\section{UTF-8 characters}

The package includes support for several accented UTF-8 characters
when used inside listings environments.

This allows code comments written with common accented characters
to compile correctly.

\begin{jupyter}[]
print("L'étudiant Ouyèté se débrouille en LaTeX !")
\end{jupyter}


\section{Version history}

The following list summarizes the evolution of the \texttt{pyjupyter} package.

\begin{itemize}
    \item \textbf{v1.0.0 (06/03/2026)}: Initial release.
    \begin{itemize}
        \item Basic Jupyter-like styling using \texttt{tcolorbox} and \texttt{listings}.
        \item Default syntax highlighting for Python.
        \item Integration of \texttt{sourcecodepro} as the default font.
    \end{itemize}
    
    \item \textbf{v1.1.0 (10/03/2026)}: Major update with enhanced flexibility.
    \begin{itemize}
        \item Global font selection: Added the \texttt{font} package option to choose between \texttt{sourcecodepro}, \texttt{beramono}, \texttt{inconsolata}, \texttt{lmtt}, \texttt{courier}, and \texttt{txtt}.
        \item Improved numbering: Redesigned the \texttt{numbered} style to ensure compatibility with any font selected in the preamble.
        \item Code size customization: Introduced the \texttt{codesize} option to globally modify the font size of code blocks from the preamble.
    \end{itemize}
    \item \textbf{v1.2.0 (15/03/2026)}: Added support for including external Python files.
    \begin{itemize}
        \item New command \verb|\inputpythonfile| for embedding Python files in a Jupyter-style box.
        \item Ability to display only specific lines using the \texttt{firstline} and \texttt{lastline} options.
        \item Full support for syntax highlighting, line numbering, font customization and custom box options within included files.
    \end{itemize}
\end{itemize}



\end{document}