📋 AI Task: Generate GitHub Repository Documentation
Copy or adapt this Markdown prompt when asking an LLM to generate repository documentation. Provide sanitized code and schema context only; do not paste individual-level records, PHI, PII, credentials, private paths, controlled-access data, or sensitive logs.
Use the project’s existing environment files as the source of truth. For Conda setup, consult Miniforge3; for an R project with an renv.lock, document the renv restore workflow.
## **🎯 Goal**
Your primary goal is to generate accurate documentation for a GitHub repository, including a `README.md` file and individual documentation files for specific tools/scripts within its existing documentation directory (or repository-relative `docs/` for a new repository). Document the environment the project actually uses, including Mamba (Conda) or renv where applicable.
---
## **⚙️ Inputs & Configuration**
**Please provide the following information:**
1. **Repository Name:** (Optional) `[User to provide, e.g., "Data Processing Utilities"]` - *Use the existing repository name when available. For a new repository without a name, use a clearly marked placeholder and suggest a name for review.*
2. **Primary Scripting Language(s):** `[User to specify, e.g., "R and Python", "Python only", "R (tidyverse)"]`
3. **Target Python Version:** (Optional) `[e.g., 3.11]` - *Read the declared version from existing manifests, lockfiles, or CI configuration; verify the installed version when execution is available. If unknown, say so.*
4. **Target R Version:** (Optional) `[e.g., 4.3]` - *Read the declared version from existing manifests, lockfiles, or CI configuration; verify the installed version when execution is available. If unknown, say so.*
5. **Developer Name / Maintainer:** `[User to provide, e.g., "Dr. Jane Doe"]`
Do not provide protected data, private storage paths, credentials, sensitive command output, or real example rows. Use schemas, synthetic fixtures, and approved aggregate outputs only.
**Default Settings (Can be overridden by user request):**
* **GitHub Organization:** [FritscheLab](https://github.com/FritscheLab)
* **License:** Preserve the existing LICENSE. For a new project, [GNU General Public License v3.0](https://www.gnu.org/licenses/gpl-3.0.html) is a proposed default for the maintainer to confirm, not an inferred license.
* **Current Year:** `[Dynamically Insert Current Year]` (YYYY)
* **Current Date:** `[Dynamically Insert Current Date]` (YYYY-MM-DD; record the actual verification date)
**Input Scripts:**
* Here is the sanitized code for each script that requires documentation. You will analyze these to infer dependencies, usage, and functionality. Do not request data rows or sensitive logs.
```text
### 📄 scripts/[script_filename_1.ext] ###
```
```[language_hint_e.g._python_or_r]
# Paste sanitized script 1 code here
```
```text
### 📄 scripts/[script_filename_2.ext] ###
```
```[language_hint_e.g._python_or_r]
# Paste sanitized script 2 code here
```
---
## **🚀 Generation Process**
**Pre-computation Steps:**
1. **Analyze Scripts:** Parse the provided script(s) to:
* Identify imported libraries/packages (e.g., `import pandas`, `library(tidyverse)`).
* Identify command-line argument definitions (e.g., using `argparse`, `optparse`).
* Infer the main purpose and functionality based on code structure, comments, and function names.
2. **Inspect Environment Files:** Read existing manifests and lockfiles (such as `environment.yml`, `renv.lock`, `pyproject.toml`, or requirements files), runtime version files, and CI configuration. Distinguish declared versions from versions actually tested. Imports identify candidate dependencies; verify package names and installation sources before writing install commands. Do not invent dependencies or claim compatibility that was not checked.
3. **Repository Context:** Use the existing name, license, directory structure, and documentation conventions. Mark unresolved information clearly and continue with the sections that the code supports.
**Output Generation:**
1. Generate the `README.md` file according to the structure specified below.
2. For *each* script provided, generate its documentation in the repository's existing location. If no convention exists, use repository-relative `docs/[script_filename_base].md` with the structure below.
---
## **📄 README.md Structure**
Generate a `README.md` file with the following sections, populating content based on the inputs and script analysis:
### **1. Title**
* Use the chosen **Repository Name**.
### **2. Badges (Optional but Recommended)**
* Add only badges supported by an existing license or workflow. Use the following license badge only when the repository is licensed under GPL v3.
```md
[](https://www.gnu.org/licenses/gpl-3.0)
```
### **3. Description**
* Write a concise overview of the repository's purpose, the problem it solves, and its key features, informed by the script analysis. Mention the primary language(s) used.
### **4. Installation**
* Prefer the repository's documented restore command and existing environment files. Do not replace an established environment with a newly guessed package list.
* When the project uses Conda, link to [Miniforge3](https://github.com/conda-forge/miniforge) for installation. Use the declared environment name, or `[RepositoryName]_env` for a proposed new environment.
* Include only the languages and versions the project requires. If a version or installation source is unverified, mark it as unresolved rather than selecting a supposed recent stable release.
* If `renv.lock` is present, document `Rscript -e 'renv::restore()'` from the project root, together with the repository's bootstrap instructions and the R version recorded in the lockfile. Explain that system libraries and the R runtime must also be available.
* Example for a project that already provides `environment.yml`:
~~~md
## Installation
Install [Miniforge3](https://github.com/conda-forge/miniforge), then restore the declared environment from the repository root:
```sh
mamba env create -f environment.yml
conda activate [RepositoryName]_env
```
Replace the environment name with the name declared in `environment.yml`.
Record the tested operating system, runtime versions, and verification date (YYYY-MM-DD).
~~~
* If no environment file exists, list verified requirements separately and propose an environment file for review. Treat `[python_version]`, `[r_version]`, `[inferred_r_package_1]`, `[inferred_r_package_2]`, `[inferred_python_package_1]`, and `[inferred_python_package_2]` as unfilled placeholders, never executable dependency specifications.
### **5. Requirements**
* List the primary requirements.
* **Operating System:** State tested platforms and distinguish them from untested compatibility assumptions.
* **Software:** List the environment tools actually required by the project.
* **Packages:** List dependencies verified against code and manifests, and identify which file records their versions. Do not guess version numbers or imply an unrun installation succeeded.
### **6. Usage**
* Provide clear examples of how to run the main script(s).
* **Derive example commands** based on the script's identified command-line arguments. Use realistic placeholder values for arguments (e.g., `input.csv`, `output_directory`).
* If multiple core scripts exist, provide examples for each.
* Structure:
~~~md
## Usage
Below are example commands for running the scripts:
### Running `[script_filename_1.ext]`
```sh
[python or Rscript] scripts/[script_filename_1.ext] --[inferred_arg1] [value1] --[inferred_arg2] [value2]
```
*Briefly explain what this command does based on script analysis.*
### Running `[script_filename_2.ext]`
```sh
[python or Rscript] scripts/[script_filename_2.ext] --[inferred_argA] [valueA] ...
```
*Briefly explain what this command does.*
~~~
### **7. Project Structure**
* Illustrate the typical directory layout. Adapt based on the provided scripts (e.g., only include R/Python specific elements if applicable).
```md
## Project Structure
📂 **[RepositoryName]/**
├── 📁 data/ # Example or placeholder input data
├── 📁 docs/ # Detailed documentation for each script
│ └── 📜 [script_filename_base].md
├── 📁 scripts/ # Source code for the tools
│ └── 📜 [script_filename_1.ext]
├── 📜 .gitignore # Specifies intentionally untracked files git should ignore
├── 📜 LICENSE # [License Name, e.g., GNU GPLv3] License file
└── 📜 README.md # This file
```
### **8. Contributing**
* Include standard contribution guidelines (Fork, Branch, Commit, PR). Mention issue tracking on GitHub.
### **9. License**
* State the existing or maintainer-confirmed license clearly, linking to the license file or URL. If it is unresolved, leave an explicit placeholder.
```md
## License
This project is licensed under the terms of the [License Name]. See the [LICENSE](LICENSE) file for details or visit [License URL].
Copyright (c) [Current Year], [GitHub Organization / Developer Name]
```
### **10. Contact**
* Provide contact information or point to the GitHub repository for issues/questions.
```md
## Contact
For questions, bug reports, or feature requests, please open an issue on the [GitHub Repository Issues page](https://github.com/[GitHub Organization]/[RepositoryName]/issues).
Maintained by: [Developer Name / Maintainer] ([GitHub Organization Link])
```
---
## **📖 Script Documentation Structure**
For *each* provided script (e.g., `scripts/process_data.py`), use its existing documentation path, or repository-relative `docs/process_data.md` when no convention exists. Include the following sections:
### **1. Tool Name**
* Use the base name of the script file (e.g., `process_data.py`).
### **2. Purpose**
* **Analyze the script's code and comments/docstrings** to provide a clear, concise description of what the script does.
### **3. Inputs & Outputs**
* **Inputs:**
* **Arguments:** List the command-line arguments identified from the script's argument parser (`argparse`, `optparse`, etc.). Include their names, expected data types (if discernible), and descriptions (from the parser's help text).
* **Input Files:** Describe the expected format of any input files (e.g., "CSV file with columns 'ID', 'Date', 'Value'").
* **Outputs:** Describe the files or results generated by the script (e.g., "Outputs a processed CSV file to the specified output directory," "Generates a plot named 'result.png'").
### **4. Usage Example**
* Provide a specific, detailed command-line example for *this* script, using its actual arguments derived during analysis. Explain the example.
### **5. Best Practices / Notes**
* (Optional but helpful) Include any tips for using the script effectively, potential limitations, or important assumptions based on script analysis (e.g., "Ensure input data is sorted by date," "Requires at least 8GB RAM for large datasets").
### **6. Error Handling / Troubleshooting**
* (Optional but helpful) List any common errors users might encounter and suggest solutions (e.g., "FileNotFoundError: Check input file path," "MemoryError: Try processing data in chunks or use a machine with more RAM"). This may require more sophisticated analysis or common patterns.
---
**Generate the documentation supported by the repository. Run documented examples with synthetic fixtures when possible, report commands and results, and clearly label any commands or compatibility claims that were not verified.**