Code Formatter Extended

Code Formatter Extended is a self‑contained web application for converting Python source files into beautifully formatted documents. It renders syntax‑highlighted code with optional titles and descriptions, and can export to HTML, RTF, DOCX, or a batch ZIP of DOCX files. Profiles allow you to save and reuse your preferred formatting settings.

Features

• Syntax highlighting using Pygments with multiple built‑in themes (Auto Light/Dark, Visual Studio Dark, GitHub Light/Dark, Solarized Light/Dark, Monokai, Dracula, Gruvbox Light/Dark) and full custom colour support.
• Metadata extraction: automatically pull a title and description from the first module docstring, or specify them manually.
• Collapsible panels: hide or show the metadata and file selection sections to maximise space for editing code.
• Live preview: see how your code will look with the current settings before exporting.
• Export formats: download your formatted code as standalone HTML, RTF, DOCX, or a ZIP of multiple DOCX files when processing a batch of source files.
• Profile management: save, load and delete formatting configurations using a simple modal dialog. Profiles are stored in a local SQLite database.

Getting Started

These instructions will help you set up and run the application on your local machine for development and testing purposes. The application is written in Python and requires a modern web browser.

Prerequisites

• Python 3.11 or higher
• Node.js is not required; all JavaScript assets are included statically.

Installation

1. Clone this repository or extract the source archive:

   git clone https://github.com/faruk-ahmad/code-formatter-ext.git
   cd code-formatter-ext

2. (Optional) Create and activate a virtual environment. This step is recommended to isolate the project dependencies:

   python -m venv .venv
   source .venv/bin/activate  # On Windows use `.venv\Scripts\activate`

3. Install the Python dependencies:

   pip install -r requirements.txt

Running the Application

The application sources live under the src/ directory. To run the development server locally you can use the provided run.py entry script:

python run.py

This starts a Uvicorn server on port 8000 and enables hot reloading. Open your browser and navigate to http://127.0.0.1:8000 to access the web interface. You can now paste or upload Python code, adjust the formatting options, preview the result and export to various formats.

Running with Docker

Alternatively, you can build and run the server inside a Docker container. The repository includes a Dockerfile and docker-compose.yml for convenience. Make sure Docker Desktop or another container runtime is running on your system before invoking these commands:

# Build the image
docker build -t code-formatter-ext .

# Run the container exposing port 8000
docker run -p 8000:8000 code-formatter-ext

Or using Docker Compose (v2 syntax):

# Ensure the docker daemon is running then use:
docker compose up --build

Docker will mount a volume for persistent profile storage. Visit http://localhost:8000 in your browser to use the application.

Profiles

Profiles let you store and recall combinations of formatting settings. Click the Manage button in the top bar to open the profile dialog. From here you can select an existing profile, save your current settings under a new name, or delete profiles that you no longer need.

Profiles are persisted in a local SQLite database called profiles.db in the project root. Deleting this file will erase all saved profiles.

Contributing

Contributions are welcome! If you have suggestions for improvements or would like to add support for additional languages or export formats, please see CONTRIBUTING.md for guidelines.

License

This project is licensed under the terms of the MIT License. See LICENSE for full details.