Add scaladoc and examples for TVaR methods

[Copilot]

This PR adds comprehensive documentation for the Tail Value at Risk (TVaR) methods in vecxt/src/tvar.scala as requested in #226.

Changes

Scaladoc Comments Added

Added detailed scaladoc comments to three previously undocumented methods:

• tVar: Calculates Tail Value at Risk (TVaR), also known as Conditional Value at Risk (CVaR) or Expected Shortfall. TVaR represents the expected value of losses in the tail beyond the VaR threshold.

• qdep: Calculates tail dependence between two distributions. This measures the proportion of observations that appear in both tails at a given confidence level, useful for understanding co-movement of extreme values.

• tVarIdx: Returns a boolean mask indicating which elements are in the tail, useful for identifying which observations contribute to tail risk.

Documentation Examples

Added a new "Risk Measures (TVaR/VaR)" section to site/docs/examples.md with practical examples for all six methods in the tvar.scala file:

// Calculate Value at Risk and Tail Value at Risk
val losses = NArray[Double](10.0, 25.0, 15.0, 50.0, 5.0, 30.0, 20.0, 8.0, 45.0, 12.0)
val var90 = losses.VaR(0.90)
val tvar90 = losses.tVar(0.90)

// Calculate both together (more efficient)
val result = losses.tVarWithVaR(0.90)

// Batch calculation for multiple confidence levels
val alphas = NArray[Double](0.85, 0.90, 0.95, 0.99)
val results = losses.tVarWithVaRBatch(alphas)

// Get tail mask and calculate tail dependence
val tailMask = losses.tVarIdx(0.90)
val tailDep = losses1.qdep(0.90, losses2)

Each example includes inline comments explaining what the method does and how to interpret the results.

CI Workflow Update

Updated the CI workflow to build documentation from the PR branch during pull requests, allowing documentation changes to be validated before merging. The workflow now:

• Builds documentation from the PR branch for pull requests
• Continues to build from main for production deployments

Testing

• All existing tests pass
• Code formatted according to project standards
• Compiles successfully on JVM target
• Site generation verified locally and will now work correctly in CI for PRs

Fixes #226

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Doc TVaR</issue_title>
<issue_description>For each of the extension methods in "vecxt/src/tvar.scala".

• Write scaladoc
• include a single example using each method on the "arrays" page of the documentation
  </issue_description>

Comments on the Issue (you are @copilot in this section)

Fixes #42

---

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.

[Quafadas]

@copilot merge in the main branch. The CI is saying failure - can you explain why?

[Copilot]

@copilot merge in the main branch. The CI is saying failure - can you explain why?

I've merged the main branch into this PR (commit 51d6855).

The CI failure is expected because the site job was recently changed to run on PRs, but it always checks out and builds from the main branch (lines 119-123 in ci.yml). This means:

1. The site job runs for PRs now (after the CI workflow update)
2. But it explicitly runs git checkout -f main and git reset --hard origin/main
3. So it builds the documentation from main, not from the PR branch

The site generation will work correctly once this PR is merged to main. The documentation examples I added work locally (site generation completed successfully when I tested it). The CI behavior is by design - the site job is intended to always build from main to ensure consistent published documentation.

[Quafadas]

@copilot can you update the CI so that it picks up the documentation on branch in CI?

[Copilot]

@copilot can you update the CI so that it picks up the documentation on branch in CI?

Updated the CI workflow in commit 230e10e. The site job now checks the event type:

• For pull requests: builds documentation from the PR branch
• For main branch: builds documentation from main (production behavior)

The site generation will now pick up the documentation changes from this PR.

[Copilot]

Pull Request Overview

This PR adds comprehensive documentation for Tail Value at Risk (TVaR) methods in the vecxt library to address issue #226. The changes focus on improving developer experience by providing clear API documentation and practical usage examples for risk management functionality.

Key changes:

• Added detailed scaladoc comments to three undocumented TVaR methods explaining their purpose, parameters, and return values
• Created a new "Risk Measures (TVaR/VaR)" section in the examples documentation with practical code samples
• Updated CI workflow to build documentation from PR branches for validation

Reviewed Changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.

File	Description
vecxt/src/tvar.scala	Added scaladoc comments to qdep, tVar, and tVarIdx methods with detailed explanations
site/docs/examples.md	Added comprehensive examples section demonstrating all TVaR/VaR methods with inline explanations
.github/workflows/ci.yml	Updated CI to build docs from PR branch for pull requests instead of always using main