Skip to content

Latest commit

 

History

History
209 lines (164 loc) · 11.8 KB

FILE_STRUCTURE.md

File metadata and controls

209 lines (164 loc) · 11.8 KB

File structure

Top-level layout

  • AGENTS.md: agent instructions and workflow guardrails.
  • README.md: repo overview, quick start, and doc links.
  • docs/: repository documentation and style guides.
  • problems: generator scripts, domain libraries, and content banks.
  • data: YAML/CSV/text inputs used by generators.
  • images: static images referenced by question HTML.
  • tests: pytest suites and lint helpers.
  • tools: utilities for audits, index generation, YAML, and images.
  • devel: release and changelog tooling.
  • source_me.sh: environment setup for Python 3.12.
  • pip_requirements.txt: Python dependencies.
  • Brewfile: optional Homebrew dependencies.
  • LICENSE.LGPL_v3: LGPLv3 license text for code.
  • LICENSE.CC_BY_4_0: CC BY 4.0 license text for non-code content.
  • VERSION: repo version string.

Problem generator subdirectories

  • biochemistry-problems: biochemistry generators and libraries.
  • biophysics-problems: biophysics generators (e.g. FRET color problems).
  • biostatistics-problems: statistics and analysis generators.
  • chi_square: chi-square generators with descriptive chi2- filenames and chisquarelib.py helpers.
  • cell_biology-problems: cell biology generators.
  • dna_profiling-problems: DNA profiling and gel electrophoresis.
  • inheritance-problems: genetics and inheritance generators.
  • laboratory-problems: lab-focused generators.
  • molecular_biology-problems: molecular biology generators.
  • matching_sets: YAML banks for matching questions.
  • ordering: keyed YAML banks and paired native/MC ordering converters.
  • multiple_choice_statements: YAML banks and tools for statement-based MC questions.
  • TEMPLATE.py: generator script template.

Library modules

Domain-specific helper libraries live near the generators that use them.

Biochemistry libraries

Genetics libraries

Pedigree libraries

Molecular biology and DNA profiling libraries

Phylogenetic tree libraries

  • treelib: tree generation, sorting, and rendering helpers.

Data and content banks

  • data: YAML/CSV/text inputs used by generators.
  • matching_sets: matching-set YAML banks by topic.
  • multiple_choice_statements: statement-based MC YAML banks and utilities.
  • images: static PNG/JPG assets referenced in question HTML.

Tools and tests

Tools directory

Devel directory

Release and changelog tooling (sharing changelog_lib.py).

Tests directory

Generated artifacts

Generated outputs are ignored by git (see .gitignore).

  • bbq-*.txt: Blackboard text upload format question files.
  • bez-*.zip: validated Blackboard pool packages created with --bbexport.
  • qti*.zip: QTI package exports.
  • selftest-*.html: HTML preview files for question self-testing.
  • pyflakes.txt: pyflakes static analysis output.
  • ascii_compliance.txt: ASCII compliance output from tests.
  • *.py[cod]: compiled Python bytecode.
  • .DS_Store: macOS folder metadata.
  • *.html: includes generated HTML such as all_gene_trees-3-leaves.html.

Documentation map

All documentation lives in docs/ except for root-level files required by convention.

Root-level docs (required by convention):

  • AGENTS.md: agent instructions and repository workflow guardrails.
  • README.md: project purpose, examples, and quick start.
  • LICENSE.LGPL_v3: LGPLv3 license text for code.
  • LICENSE.CC_BY_4_0: CC BY 4.0 license text for non-code content.

Where to add new work

New question generators

  • Copy TEMPLATE.py to the appropriate problems/*-problems/ subdirectory.
  • Rename to match the question topic using snake_case.
  • Update argparse help text, question logic, and output filename.

New library modules

  • Place domain-specific helpers in the corresponding problems/*-problems/ subdirectory.
  • Use a *lib.py suffix for helper libraries when it improves clarity.
  • Import and use from generator scripts in the same subdirectory.

New content inputs

  • Place shared YAML/CSV/text inputs under data.
  • Place matching question banks under matching_sets.
  • Place statement-based MC banks under multiple_choice_statements.
  • Add static images under images.

New tests

  • Add pytest tests under tests or libs as appropriate.
  • Add YAML validation tests under yaml.
  • Run pytest tests/ (includes the pyflakes, ASCII, and Markdown-link gates) after changes.

New documentation

  • Place new docs under docs/ using SCREAMING_SNAKE_CASE filenames.
  • Update CHANGELOG.md when making changes.
  • Follow MARKDOWN_STYLE.md for formatting.