Common questions and answers about the Research Project Template
Quick Reference: Getting Started | Troubleshooting | How To Use
A: This is a template for research projects that provides a standardized structure with test-driven development, automated PDF generation, and professional documentation workflows. It's for academic papers, scientific documentation, technical reports, and any project requiring professional output.
A: Click the "Use this template" button on GitHub to create a new repository with this structure, then clone it and customize it for your project. The template includes everything you need to get started immediately.
A: The template is primarily designed for Python projects, but the documentation and PDF generation features work with any content. The core architecture focuses on Python with testing and build automation.
A: The structure follows the "thin orchestrator pattern" which separates business logic (src/) from orchestration (scripts/). This ensures maintainable, testable code while keeping scripts lightweight and focused on their specific tasks.
A:
projects/{name}/src/(Layer 2) contains business logic, algorithms, and mathematical implementations with robust test coverage.projects/{name}/scripts/are thin orchestrators that import use Layer 2 methods to generate specific figures, data, and outputs.scripts/(Layer 1 Root) are generic pipeline entry points that discover and execute the project-specificscripts/.
A: Coverage requirements are: 90% minimum for project code (projects/{name}/src/) and 60% minimum for infrastructure/. The build pipeline enforces these via CI. Live achieved percentages per exemplar live in ../_generated/COUNTS.md — don't hardcode them into prose; link to the canonical source.
A: The template uses Pandoc to convert markdown files to LaTeX, then XeLaTeX to generate PDFs. The ./run.sh entry point (or scripts/execute_pipeline.py) runs the full pipeline sequence: tests, analysis scripts, PDF rendering, validation, and copy-out, with optional LLM stages when not using --core-only. Stage layout is documented in RUN_GUIDE.md.
A: Yes! The LaTeX templates and Pandoc configurations can be customized. You can modify styles, add custom formatting, or even generate other formats like HTML or Word documents.
A: The template includes a cross-referencing system that automatically generates links between markdown files. See markdown-template-guide.md for detailed instructions.
A: You can remove the PDF-related utilities and focus on the core project structure. The template is modular, so you can use only the parts you need.
A: Test coverage ensures that your core business logic works correctly and remains reliable as you make changes. It's especially important for research projects where accuracy is critical.
A: Create test files in the projects/{name}/tests/ directory that follow the naming convention test_*.py. Use pytest fixtures and ensure your tests cover all code paths in your projects/{name}/src/ modules.
A: While pytest is the default, you can adapt the template to use other testing frameworks. Just update the build scripts and CI configuration accordingly.
A: Customize your project by editing projects/{name}/manuscript/config.yaml or setting environment variables (AUTHOR_NAME, PROJECT_TITLE, etc.). See Configuration Guide for details.
A: Absolutely! The template is designed to be extensible. You can add new output formats by creating new scripts and updating the build pipeline.
A: The template provides hooks and utilities that make it easy to integrate with CI/CD systems, documentation generators, and other development tools.
A:
- Ensure all tests pass with required coverage (90% project, 60% infra)
- Check that all required dependencies are installed
- Verify that your markdown files are properly formatted
- Check the build logs for specific error messages
A:
- Verify Pandoc and LaTeX are properly installed
- Check that your markdown syntax is correct
- Ensure all referenced figures and files exist
- Review the LaTeX templates for any syntax issues
A:
- Run tests with verbose output:
uv run pytest projects/{name}/tests/ -v - Use pytest's debugging features:
uv run pytest --pdb - Check coverage reports:
uv run pytest projects/{name}/tests/ --cov=projects/{name}/src --cov-report=html - Review the test output for specific error messages
A: Yes! The template includes issue templates, pull request templates, and contribution guidelines that make collaboration easy and professional.
A: Fork the repository, make your improvements, and submit a pull request. See contributing.md for detailed guidelines.
A: Yes, the template is licensed under the Apache License 2.0, which allows commercial use, modification, and distribution.
A: Watch the repository for updates, check the repository releases and commit history, and consider contributing improvements back to the community.
A: Importable infrastructure package names and measured counts are tracked in COUNTS.md. See the Modules Guide for the current package map and per-module guides.
A: See the Modules Guide for usage examples and integration patterns. Each module includes API documentation and best practices.
A: API reference for all modules is available in API Reference, including function signatures, parameters, return values, and examples.
A: See .github/README.md for GitHub Actions setup, automated testing, and repository workflows.
A: Yes. Start with .github/workflows/README.md, then adapt workflows to run uv sync and the pipeline entry point you need (see RUN_GUIDE.md).
A: See the root README.md for uv install/sync commands, and use uv run to execute scripts consistently.
A: Start with uv lock --upgrade (if used in your workflow) and re-run uv sync. If conflicts persist, simplify optional groups and ensure project dependencies are represented in the root environment when running under the root venv (see docs/AGENTS.md).
A: See the Performance Optimization Guide for strategies to reduce build times, including parallel execution, caching, and optimization techniques.
A: See Performance Optimization Guide for measurement and tuning, and RUN_GUIDE.md for pipeline execution details.
A:
- Check the documentation in the docs/ directory
- Open an issue on GitHub for specific problems
- Review the examples and workflow guides
- Join the community discussions
For detailed documentation, see README.md, ../core/architecture.md, and ../core/workflow.md.
A: Yes! Use the feature request issue template to suggest improvements. We welcome all suggestions that would benefit the broader community.
Still have questions? Open an issue and we'll help you out! 🚀
For more information, see contributing.md and code-of-conduct.md.