Template Project: Documentation Hub

Welcome to the documentation for the template-project — a minimal, modern Python project template designed for research groups and scientific code development.

This template includes tools for testing, documentation, versioning, citation, publishing to PyPI, and more. Whether you’re working solo or collaborating in a team, this guide will help you get started and stay consistent.

Getting started

• Getting Started: Setup and Installation
  • Step 1: Get the Repository
  • Step 2: Set Up a Python Environment
  • Step 3: Install the Package (Editable Mode)
  • Step 4: Test That It Works
  • Optional: Use GitHub Desktop Instead of Terminal
  • Git Workflows
  • You’re All Set!
• Customisation Checklist for New Projects
  • 📁 Core Package and Import Paths
  • 🧪 Testing
  • ⚙️ Configuration and Metadata
  • 📚 Documentation
  • 📝 Citation and License
  • 📄 Other Markdown Files
  • 🛠 Optional Automation
• What’s in This Template Project?
  • 🔍 Project Structure Overview
• 📁 template-project File Structure
  • 🔍 Notes
  • 🔰 The Basics (Always Included)
  • 🧰 Python Packaging and Development
  • 🧪 Testing and Continuous Integration
  • 📝 Documentation
  • 🧾 Metadata and Community
  • ✅ Summary

GitHub basics

• Getting Started with GitHub
  • 🌐 Git vs GitHub
  • 📦 What Is a Repository?
  • 🍴 What Is a Fork?
  • 🌿 What Is a Branch?
  • 🔁 What Is a Pull Request?
  • 🐛 What Are Issues?
  • ⚙️ What Are GitHub Actions?
  • 🖥 GitHub Desktop (Optional)
  • 🔗 More Help
• GitHub Tags for Oceanographic Projects
  • 🌊 Core Oceanography Tags
  • 📊 Data & Analysis
  • 🔬 Specific Measurements & Phenomena
  • 🛠 Technical Tools & Libraries
  • 🧪 Specialized Areas
  • 📡 Data Sources & Standards
  • 🎯 How to Add Tags to Your Repository
  • 💡 Contributing to This List
• Solo Git Workflow for Your Project
  • 1. Keep main Clean
  • 2. Work on a Branch
  • 3. Option A: Merge the Branch (Fast-forward style)
  • 3. Option B: Open a Pull Request (recommended, even solo!)
  • 4. Rinse and Repeat
  • (Optional) Sync Across Devices
  • Tips
  • Cheatsheet: Handy Git Commands
• Collaborating on Someone Else’s Repository
  • 1. Fork the Repository
  • 2. Clone the Repository
  • 3. Add the Original Repo as “Upstream”
  • 4. Create a Branch for Your Changes
  • 5. Make and Commit Your Changes
  • 6. Push Your Branch to GitHub
  • 7. Open a Pull Request
  • 8. Sync Your Fork (for Next Time)
  • Tips
  • Cheatsheet: Handy Git Commands

Development Guide

• Project Style Guide
  • 🧑‍💻 Python Coding Conventions
  • 🗂 Dataset & Metadata Conventions
  • 🔁 Automating Formatting (Optional)
  • 🛠 Optional: VSCode Setup for Auto-formatting
  • 💡 Future Considerations
• Writing and Running Tests
  • 📁 Where Tests Go
  • ✍️ Writing Your First Test
  • ▶️ Running Tests Locally
  • 🛠 Recommended Conventions
  • 📊 Checking Test Coverage
  • Summary Cheatsheet
• Building Documentation Locally
  • 📦 Step 1: Install Documentation Dependencies
  • 🏗 Step 2: Build the Docs
  • 🖋 Writing in Markdown or reStructuredText
  • 🧠 Tips for Clean Docs
  • 🧪 Rebuild After Changes
  • 📚 Learn More
  • Summary Cheatsheet
• Setting Up Pre-commit Hooks
  • 🧠 What Are Pre-commit Hooks?
  • ⚙️ Step-by-step Setup
  • 💻 Using Pre-commit in Your Workflow
  • 📋 Cheatsheet
  • 🔗 Learn More
• GitHub Actions: Automating Your Project
  • 🤖 What Is a GitHub Action?
  • 🧪 tests.yml: Run Your Tests Automatically
  • 🧱 docs.yml: Test Your Documentation Build
  • 🚀 docs_deploy.yml: Publish to GitHub Pages
  • 📦 pypi.yml: Publish a Package to PyPI
  • 🛠️ How to Customize These Workflows
  • ✅ Summary

Project Management

• How to Cite This Project
  • 📄 What is CITATION.cff?
  • ✍️ Example CITATION.cff
  • 🌐 Linking to a DOI with Zenodo
  • 🧩 Best Practices
• Publishing Your Project to PyPI
  • 📁 Step 1: Prepare Your Project
  • 📝 Step 2: Edit Your Project Metadata
  • 🛠️ Step 3: Build Your Package
  • 🧪 Step 4: Test on TestPyPI
  • 🚀 Step 5: Upload to PyPI
  • 🤖 Optional: Automate Publishing with GitHub Actions
  • ✅ Summary
• Transferring a Repository to an Organisation
  • 📦 Why Transfer to an Organisation?
  • 🔁 Steps for Transferring a Repository
  • ⚙️ Post-Transfer Clean-up
  • 👤 Final Step for Original Owner

Users' guide

• template-project demo

Help and reference

• GitHub Repo
• template_project API
  • load_dataset()
  • load_sample_dataset()
  • plot_monthly_transport()
  • show_attributes()
  • show_variables()
  • save_dataset()
  • convert_units_var()
  • reformat_units_var()
  • apply_defaults()
  • download_file()
  • get_default_data_dir()
  • resolve_file_path()
  • safe_update_attrs()
• FAQ / Troubleshooting
  • 🐍 Import Error: from template_project import plotters
  • 💥 Pip install error in GitHub Actions
  • 🤔 What’s the difference between template-project and template_project?
  • 😬 I accidentally committed to main instead of a branch
  • 🚨 Continuous Integration (CI) is failing
  • 🧭 How do I check which branch I’m on?
  • 🔄 I cloned the repo but don’t see the latest updates
  • ✍️ I made changes but GitHub doesn’t show them
  • 📋 I opened a pull request — what happens now?
  • 🙋 Still stuck?

These documentation pages were created based on processes used to develop and maintain http://github.com/OceanGlidersCommunity/glidertest and edited using chatGPT.