Project Structure

Overview of Documentation Folders

This project provides two separate documentation folders:

  • /template-docs/: This is a ready-to-use Sphinx documentation template for users of this Python project template. Copy or rename this folder to /docs/ in your own project to quickly set up Sphinx documentation. It includes example configuration, build scripts, and a formatting script.

  • /template-sphinx-documentation/: This folder contains the documentation for the template project itself (i.e., the documentation you are reading now). It is not intended to be copied or used as a template by users.

  • /docs/: This folder is used for the built HTML output of the template project’s own documentation, and is published via GitHub Pages. Do not edit by hand.

How to Use the Sphinx Template

  1. For your own project: - Copy or rename /template-docs/ to /docs/ in your new repository. - Edit the contents (add your .rst or .md files, update conf.py, etc.). - Use the provided Makefile or make.bat to build your documentation. - The included fix_rst_formatting.py script will help keep your RST files clean and warning-free.

  2. For this template project: - /template-sphinx-documentation/ is only for the documentation of this template itself. You do not need to use or copy it for your own project.

Directory Layout

The template follows a standardized directory layout designed to promote good Python project organization:

cursor-python-template/
├── .cursor/                    # Cursor editor configuration
│   └── rules/                  # Cursor AI rules
├── .github/                    # GitHub configuration (optional)
│   └── workflows/              # GitHub Actions workflows (optional)
├── template-docs/              # Sphinx documentation template for users
│   ├── conf.py                 # Sphinx configuration
│   ├── fix_rst_formatting.py   # Automatic RST formatting script
│   ├── Makefile                # Unix build script
│   ├── make.bat                # Windows build script
│   ├── index.md                # Example index file
│   └── rules-documentation/    # Example RST documentation
├── template-sphinx-documentation/  # Documentation for this template project
│   ├── source/                 # Sphinx documentation source files
│   ├── fix_rst_formatting.py   # Automatic RST formatting script
│   ├── Makefile                # Unix build script
│   └── make.bat                # Windows build script
├── docs/                       # Built HTML output for GitHub Pages (do not edit by hand)
├── scripts/                    # Utility scripts
├── src/                        # Source code
│   └── project_name_placeholder/ # Main package directory (to be renamed)
│       └── __init__.py         # Package initialization file
├── tests/                      # Test files
│   └── __init__.py             # Test package initialization
├── .gitignore                  # Git ignore file
├── CONTRIBUTING.md             # Contribution guidelines
├── LICENSE                     # License file
├── pyproject.toml              # Python project configuration
├── README.md                   # Project README
└── requirements.txt            # Dependencies

Key Components

.cursor/rules/

This directory contains rule files that guide Cursor’s AI in providing context-aware assistance:

  • code-review-rules.mdc: Guidelines for code review practices

  • context-detection-rules.mdc: Patterns for detecting and managing context

  • core-rules.mdc: Fundamental development principles and patterns

  • cursor-startup-rules.mdc: Rules for Cursor AI’s initialization process

  • documentation-rules.mdc: Documentation standards and requirements

  • github-issues-rules.mdc: GitHub issue management guidelines

  • github-rules.mdc: GitHub workflow and best practices

  • powershell-rules.mdc: PowerShell coding standards

  • project-plan-management-rules.mdc: Project plan management guidelines

  • project-structure-rules.mdc: Rules for project organization

  • python-rules.mdc: Python coding standards

  • testing-rules.mdc: Testing requirements and best practices

.template-docs/

This directory is a Sphinx documentation template for users of this Python project template:

  • conf.py: Sphinx configuration file

  • fix_rst_formatting.py: Script to automatically fix common RST formatting issues

  • Makefile: Unix build script (runs formatting script automatically)

  • make.bat: Windows build script (runs formatting script automatically)

  • index.md: Example Markdown index file

  • rules-documentation/: Example RST documentation

.template-sphinx-documentation/

This directory contains all Sphinx documentation source files, configuration, and build scripts for the template project itself:

  • source/: Main documentation source files (reStructuredText)

  • fix_rst_formatting.py: Script to automatically fix common RST formatting issues

  • Makefile: Unix build script (runs formatting script automatically)

  • make.bat: Windows build script (runs formatting script automatically)

src/

The src/ directory contains the main package code:

  • By default, it contains a placeholder directory project_name_placeholder/ which should be renamed to match your actual project name.

  • This follows the src layout approach, which offers several advantages including cleaner imports and more explicit installation requirements.

tests/

The tests/ directory contains all test files:

  • Test files should follow the pattern test_*.py or *_test.py

  • The test directory structure should mirror the package structure in src/

  • Tests are configured to run with pytest

/docs/

This directory contains only the built HTML output for GitHub Pages. Do not edit files here by hand. The contents are overwritten each time you build and publish the documentation.

scripts/

The scripts/ directory is for utility scripts and tools:

  • Setup scripts

  • Development utilities

  • Build scripts

  • Any other helpful automation tools

Automatic RST Formatting Script

The template includes a script to automatically fix common formatting issues in reStructuredText (RST) documentation files:

  • Script: fix_rst_formatting.py (in /template-sphinx-documentation/)

  • Purpose: - Ensures title overlines/underlines match the title length - Fixes section and subsection heading formatting - Standardizes formatting across all documentation files

  • Integration: - The script runs automatically every time you build the documentation using make html (Unix) or make.bat html (Windows) - You can also run it manually: python fix_rst_formatting.py from within /template-sphinx-documentation/

  • Benefit: - Helps prevent common Sphinx warnings and ensures professional, consistent documentation formatting.

Configuration Files

pyproject.toml

The pyproject.toml file defines the project’s metadata and build system requirements:

  • Project name, version, description, and author details

  • Dependencies and development dependencies

  • Build system configuration

  • Tool configurations (e.g., pytest, black, etc.)

requirements.txt

The requirements.txt file lists the project’s dependencies:

  • Production dependencies

  • May include version constraints

  • Used for direct installation via pip

.gitignore

The .gitignore file specifies which files should be ignored by Git:

  • Python-specific patterns (__pycache__, .pyc, etc.)

  • Environment-specific files (venv/, .env, etc.)

  • Build artifacts (dist/, build/, etc.)

  • Editor-specific files

  • OS-specific files

LICENSE

The LICENSE file contains the project’s license, by default MIT License:

  • Should be updated with the current year and project author’s name/organization

CONTRIBUTING.md

The CONTRIBUTING.md file provides guidelines for contributing to the project:

  • How to set up a development environment

  • Coding standards

  • Pull request process

  • Issue reporting guidelines