Developer Guide for torchebm¶

Table of Contents¶

1. Introduction
2. Setting Up the Development Environment
3. Prerequisites
4. Cloning the Repository
5. Installing Dependencies
6. Code Style and Quality
7. Code Formatting
8. Linting
9. Type Checking
10. Testing
11. Documentation
12. Docstring Conventions
13. API Documentation Generation
14. Contributing
15. Branching Strategy
16. Commit Messages
17. Pull Requests
18. Additional Resources

Introduction¶

Welcome to the developer guide for torchebm, a Python library focused on components and algorithms for energy-based models. This document provides instructions and best practices for contributing to the project.

Setting Up the Development Environment¶

Prerequisites¶

Ensure you have the following installed:

• Python: Version 3.9 or higher.
• Git: For version control.
• pip: Python package installer.

Cloning the Repository¶

Clone the repository using SSH:

git clone git@github.com:soran-ghaderi/torchebm.git

Or using HTTPS:

git clone https://github.com/soran-ghaderi/torchebm.git

Navigate to the project directory:

cd torchebm

Installing Dependencies¶

Install the development dependencies:

pip install -e .[dev]

This command installs the package in editable mode along with all development dependencies specified in the pyproject.toml file.

Code Style and Quality¶

Maintaining a consistent code style ensures readability and ease of collaboration.

To streamline code formatting and quality checks in your development workflow, integrating tools like Black, isort, and mypy directly into your Integrated Development Environment (IDE) can be highly beneficial. Many modern IDEs, such as PyCharm, offer built-in support or plugins for these tools, enabling automatic code formatting and linting as you write.

PyCharm Integration:

• Black Integration: Starting from PyCharm 2023.2, Black integration is built-in. To enable it:

• Navigate to Preferences or Settings > Tools > Black.

• Configure the settings as desired.

• Ensure Black is installed in your environment:

  pip install black
  

• isort Integration: While PyCharm doesn't have built-in isort support, you can set it up using File Watchers:

• Install the File Watchers plugin if it's not already installed.

• Navigate to Preferences or Settings > Tools > File Watchers.

• Add a new watcher for isort with the following configuration:

  • File Type: Python
  • Scope: Current File
  • Program: Path to isort executable (e.g., $PyInterpreterDirectory$/isort)
  • Arguments: $FilePath$
  • Output Paths to Refresh: $FilePath$
  • Working Directory: $ProjectFileDir$

• mypy Integration: To integrate mypy:

• Install mypy in your environment:

  pip install mypy
  

• Set up a File Watcher in PyCharm similar to isort, replacing the program path with the mypy executable path.

VSCode Integration:

For Visual Studio Code users, extensions are available for seamless integration:

• Black Formatter: Install the "Python" extension by Microsoft, which supports Black formatting.
• isort: Use the "Python" extension's settings to enable isort integration.
• mypy: Install the "mypy" extension for real-time type checking.

By configuring your IDE with these tools, you ensure consistent code quality and adhere to the project's coding standards effortlessly.

If you prefer to do these steps manually, please read the following steps, if not, you can ignore this section.

Code Formatting¶

We use Black for code formatting. To format your code, run:

black .

Linting¶

isort is used for sorting imports. To sort imports, execute:

isort .

Type Checking¶

mypy is employed for static type checking. To check types, run:

mypy torchebm/

Testing¶

We utilize pytest for testing. To run tests, execute:

pytest

For test coverage, use:

pytest --cov=torchebm

Documentation¶

Docstring Conventions¶

All docstrings should adhere to the Google style guide. For example:

def function_name(param1, param2):
    """Short description of the function.

    Longer description if needed.

    Args:
        param1 (type): Description of param1.
        param2 (type): Description of param2.

    Returns:
        type: Description of return value.

    Raises:
        ExceptionType: Explanation of when this exception is raised.

    Examples:
        result = function_name(1, "test")
    """
    # Function implementation

API Documentation Generation¶

The API documentation is automatically generated from docstrings using generate_api_docs.py, MkDocs, and the MkDocstrings plugin.

To update the API documentation:

1. Run the API documentation generator script:

   python gen_ref_pages.py
   

2. Build the documentation to preview changes:

   mkdocs serve
   

Contributing¶

We welcome contributions! Please follow the guidelines below.

Branching Strategy¶

• main: Contains stable code.
• feature/branch-name: For developing new features.
• bugfix/branch-name: For fixing bugs.

Commit Messages¶

Use clear and concise commit messages. Follow the format:

Subject line (imperative, 50 characters or less)

Optional detailed description, wrapped at 72 characters.

Pull Requests¶

Before submitting a pull request:

1. Ensure all tests pass.
2. Update documentation if applicable.
3. Adhere to code style guidelines.

Additional Resources¶

• Python's PEP 8 Style Guide
• Google Python Style Guide
• Black Code Formatter
• pytest Documentation

By following this guide, you will help maintain the quality and consistency of the torchebm library. Happy coding!