[WIP] Create a handbook for our group

.github/workflows/handbook.yml

@@ -0,0 +1,86 @@
+name: Build and Deploy Handbook
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'handbook/**'
+      - 'mkdocs.yml'
+      - 'pyproject.toml'
+      - '.github/workflows/handbook.yml'
+  pull_request:
+    branches:
+      - main
+    paths:
+      - 'handbook/**'
+      - 'mkdocs.yml'
+      - 'pyproject.toml'
+      - '.github/workflows/handbook.yml'
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+  pull-requests: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Build documentation
+        run: uv run mkdocs build --site-dir site
+
+      - name: Upload artifact for GitHub Pages
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./site
+
+      - name: Upload build artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: handbook-site
+          path: ./site
+
+  # Post artifact link in PR comments  
+  post-artifact:
+    if: github.event_name == 'pull_request'
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Post artifact link
+        uses: CDCgov/cfa-actions/post-artifact@main
+        with:
+          artifact-name: handbook-site
+          gh-token: ${{ secrets.GITHUB_TOKEN }}
+
+  # Deploy to GitHub Pages (only on main branch)
+  deploy:
+    if: github.ref == 'refs/heads/main'
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -44,4 +44,12 @@ Temporary Items
 .RData
 .Ruserdata
 *.Rproj
-*.html
+*.html
+
+# Python virtual environment and build artifacts
+.venv/
+site/
+__pycache__/
+*.py[cod]
+*$py.class
+uv.lock

handbook/README.md

@@ -0,0 +1,24 @@
+# ForeSITE Group Handbook
+
+This directory contains the source files for the ForeSITE Group Handbook, which is built using [MkDocs](https://www.mkdocs.org/) and the [Material theme](https://squidfunk.github.io/mkdocs-material/).
+
+## Structure
+
+- `index.md` - Homepage of the handbook
+- `r-packages.md` - Best practices for writing R packages
+- `python-libraries.md` - Best practices for writing Python libraries  
+- `shiny-apps.md` - Guidelines for building Shiny applications
+- `code-for-papers.md` - Standards for reproducible research code
+- `agile-planning.md` - Agile methodology practices for the group
+
+## Building the Handbook
+
+The handbook is automatically built and deployed using GitHub Actions. To build locally:
+
+1. Install dependencies: `uv sync`
+2. Build the site: `uv run mkdocs build`
+3. Serve locally: `uv run mkdocs serve`
+
+## Configuration
+
+The handbook configuration is defined in `mkdocs.yml` in the repository root.

handbook/agile-planning.md

@@ -0,0 +1,37 @@
+# Agile Planning
+
+!!! note "Work in Progress"
+    This chapter is a placeholder and will be expanded with detailed practices for agile project management.
+
+## Overview
+
+This chapter will cover the ForeSITE group's approach to agile software development and project management.
+
+## Topics to be Covered
+
+- Sprint planning and execution
+- Daily stand-up meetings
+- Retrospectives and continuous improvement
+- Issue tracking with GitHub
+- Milestone and release management
+- Team collaboration best practices
+- Estimation and velocity tracking
+- User story writing
+- Definition of done
+
+## Current Practices
+
+We currently follow these agile components:
+
+- **Sprints**: Bi-weekly iterations
+- **Stand-ups**: Daily 15-minute meetings when possible
+- **Retrospectives**: At the beginning of each sprint
+- **Tools**: GitHub repositories, issues, and milestones
+
+## Related Resources
+
+- [Agile Manifesto](https://agilemanifesto.org/) - Foundational agile principles
+
+---
+
+*This content will be expanded in future updates.*

handbook/code-for-papers.md

@@ -0,0 +1,28 @@
+# Code for Papers
+
+!!! note "Work in Progress"
+    This chapter is a placeholder and will be expanded with detailed best practices for writing reproducible research code.
+
+## Overview
+
+This chapter will cover best practices for writing code that accompanies academic papers and research outputs.
+
+## Topics to be Covered
+
+- Reproducible research principles
+- Code organization and structure
+- Documentation and README files
+- Data management and sharing
+- Version control for research
+- Computational environments (Docker, conda, etc.)
+- Code archiving and DOI assignment
+- Licensing considerations for research code
+- Peer review and collaboration workflows
+
+## Related Resources
+
+- [The Turing Way](https://the-turing-way.netlify.app/) - Guide to reproducible research
+
+---
+
+*This content will be expanded in future updates.*

handbook/index.md

@@ -0,0 +1,33 @@
+# ForeSITE Group Handbook
+
+Welcome to the ForeSITE Group Handbook! This handbook contains best practices and guidelines for software development and project management within our group.
+
+## About This Handbook
+
+This handbook is designed to help team members follow consistent practices across all our projects. It covers various aspects of software development, from writing packages to managing projects using agile methodologies.
+
+## Handbook Sections
+
+### Best Practices
+
+- **[Writing R Packages](r-packages.md)** - Guidelines for developing R packages
+- **[Writing Python Libraries](python-libraries.md)** - Best practices for Python development
+- **[ShinyApps](shiny-apps.md)** - Standards for building Shiny applications
+- **[Code for Papers](code-for-papers.md)** - Guidelines for reproducible research code
+- **[Agile Planning](agile-planning.md)** - Our approach to agile project management
+
+## Contributing
+
+This handbook is a living document. If you have suggestions for improvements or new sections, please:
+
+1. Create an issue in this repository
+2. Submit a pull request with your proposed changes
+3. Discuss improvements with the team during retrospectives
+
+## About ForeSITE
+
+The ForeSITE (Forecasting Science for Infectious Disease Emergencies) group develops computational tools and models for epidemic forecasting and response.
+
+---
+
+*Last updated: {{ git_revision_date_localized }}*

handbook/python-libraries.md

@@ -0,0 +1,26 @@
+# Writing Python Libraries
+
+!!! note "Work in Progress"
+    This chapter is a placeholder and will be expanded with detailed best practices for writing Python libraries.
+
+## Overview
+
+This chapter will cover best practices for developing Python libraries within the ForeSITE group.
+
+## Topics to be Covered
+
+- Project structure and packaging
+- Dependency management with uv/pip
+- Documentation with Sphinx or MkDocs
+- Testing with pytest
+- Type hints and code quality
+- Publishing to PyPI
+- Continuous integration and deployment
+
+## Related Resources
+
+- [Python Packaging Guide](https://packaging.python.org/) - Official Python packaging documentation
+
+---
+
+*This content will be expanded in future updates.*

handbook/r-packages.md

@@ -0,0 +1,25 @@
+# Writing R Packages
+
+!!! note "Work in Progress"
+    This chapter is a placeholder and will be expanded with detailed best practices for writing R packages.
+
+## Overview
+
+This chapter will cover best practices for developing R packages within the ForeSITE group.
+
+## Topics to be Covered
+
+- Package structure and organization
+- Documentation with roxygen2
+- Testing strategies
+- Continuous integration
+- CRAN submission guidelines
+- Package websites with pkgdown
+
+## Related Resources
+
+- [R Packages Book](https://r-pkgs.org/) - Comprehensive guide to R package development
+
+---
+
+*This content will be expanded in future updates.*

handbook/shiny-apps.md

@@ -0,0 +1,28 @@
+# ShinyApps
+
+!!! note "Work in Progress"
+    This chapter is a placeholder and will be expanded with detailed best practices for building Shiny applications.
+
+## Overview
+
+This chapter will cover best practices for developing Shiny applications within the ForeSITE group.
+
+## Topics to be Covered
+
+- Application architecture and structure
+- UI/UX design principles
+- Server-side logic organization
+- Data handling and reactivity
+- Testing Shiny applications
+- Deployment strategies (shinyapps.io, Docker, etc.)
+- Performance optimization
+- Security considerations
+
+## Related Resources
+
+- [Shiny Documentation](https://shiny.rstudio.com/) - Official Shiny documentation
+- [Mastering Shiny](https://mastering-shiny.org/) - Comprehensive Shiny development guide
+
+---
+
+*This content will be expanded in future updates.*

mkdocs.yml

@@ -0,0 +1,41 @@
+site_name: ForeSITE Group Handbook
+site_description: Best practices and guidelines for the ForeSITE Group
+site_url: https://epiforesite.github.io/software
+repo_url: https://github.com/EpiForeSITE/software
+repo_name: EpiForeSITE/software
+docs_dir: handbook
+
+theme:
+  name: material
+  palette:
+    - scheme: default
+      primary: blue
+      accent: blue
+  features:
+    - navigation.tabs
+    - navigation.sections
+    - navigation.expand
+    - navigation.top
+    - search.highlight
+    - search.share
+
+nav:
+  - Home: index.md
+  - Best Practices:
+    - Writing R Packages: r-packages.md
+    - Writing Python Libraries: python-libraries.md
+    - ShinyApps: shiny-apps.md
+    - Code for Papers: code-for-papers.md
+    - Agile Planning: agile-planning.md
+
+markdown_extensions:
+  - admonition
+  - codehilite
+  - pymdownx.superfences
+  - pymdownx.tabbed
+  - pymdownx.details
+  - toc:
+      permalink: true
+
+plugins:
+  - search