Set up Sphinx documentation with markdown, GitHub workflows for deployment, PDF generation, release assets, and pre-commit hooks

[Copilot]

Implements infrastructure for collaborative academic paper writing: Sphinx-based documentation system with markdown files, automated deployment to GitHub Pages, PDF artifact generation, release asset attachment, and pre-commit linting/formatting hooks.

Documentation Structure

• Sphinx with MyST parser for markdown support, Read the Docs theme
• Paper sections organized as separate markdown files:
  • introduction.md, methodology.md, decision-tree.md
  • case-studies.md, conclusions.md, references.md
• Configuration: docs/conf.py, docs/requirements.txt, docs/Makefile

GitHub Actions Workflows

Documentation Deployment (.github/workflows/docs.yml)

• Builds Sphinx HTML on push/PR
• Deploys to GitHub Pages (main branch only)
• Uses actions/upload-pages-artifact and actions/deploy-pages

PDF Generation (.github/workflows/pdf.yml)

• Combines markdown sections in order using shell loop
• Converts to LaTeX and PDF via Pandoc
• Stores combined markdown, LaTeX, and PDF as downloadable artifacts

SECTIONS=("introduction" "methodology" "decision-tree" "case-studies" "conclusions" "references")
for section in "${SECTIONS[@]}"; do
  cat "docs/${section}.md" >> output/paper.md
  echo -e "\n\n" >> output/paper.md
done

Release Assets (.github/workflows/release.yml)

• Triggers on git tag push (e.g., v1.0.0)
• Builds versioned LaTeX and PDF files (e.g., uq-tree-v1.0.0.tex, uq-tree-v1.0.0.pdf)
• Automatically attaches files to GitHub releases as downloadable assets
• Uses softprops/action-gh-release@v1 for asset upload

Pre-commit Hooks

• File quality: trailing whitespace, EOF, YAML validation, merge conflicts
• Markdown: markdownlint with custom config (.markdownlint.json)
• Python: Black, isort, flake8

Documentation

• README.md updated with build/setup instructions and release workflow
• CONTRIBUTING.md added with workflow documentation including release process
• .gitignore updated for Sphinx/Python artifacts

Setup Required

Enable GitHub Pages in repository settings: Settings → Pages → Source → GitHub Actions

Creating Releases

To create a release with attached LaTeX and PDF files:

git tag -a v1.0.0 -m "Release version 1.0.0"
git push origin v1.0.0

Original prompt

we are collaboratively writing a paper with the working title "A decision tree for practitioners needing uncertainty quantification for their deep learning project"

• set up a skeleton for the paper using sphinx documentation with markdown files
• add workflows that build and deploy the documentation to github pages
• add workflow that converts the markdown to latex using pandoc, renders the pdf and stores the latex and pdf files as artifacts
• add pre-commit hooks for linting and formatting

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[thawn]

@copilot latex and pdf should be added as release files

[Copilot]

@copilot latex and pdf should be added as release files

Added in commit 9fefda5. Created .github/workflows/release.yml that triggers on git tag pushes and attaches versioned LaTeX and PDF files to releases (e.g., uq-tree-v1.0.0.tex and uq-tree-v1.0.0.pdf). Updated README and CONTRIBUTING with release instructions.