simulate_summary(): Enhance to track finite populations & improve documentation

[jamesmbaazam]

• Please check if the PR fulfills these requirements

• I have read the CONTRIBUTING guidelines
• A new item has been added to NEWS.md
• Tests for the changes have been added (for bug fixes / features)
• Docs have been added / updated (for bug fixes / features)

• What kind of change does this PR introduce? (Bug fix, feature, docs update, ...)

• An enhancement to simulate_summary() to handle finite populations
• Improvements to the documentation to inherit sections like the references from simulate_chains(), a section to explain the difference between simulate_summary() and simulte_chains(), improved examples, a details section.
• The section on specifying the generation time was wrongly inherited as a subsection from simulate_chains(), so it has been removed.

• What is the current behavior? (You can also link to an open issue here)

Simulates a vector of transmission chains assuming an infinite population

• What is the new behavior (if this is a feature change)?

Simulates a vector of transmission chains with the ability to limit the outbreak to a finite population size

• Does this PR introduce a breaking change? (What changes might users need to make in their application due to this PR?)

Maybe. The function arguments have been re-arranged and the dots argument has been moved in front of the optional arguments to ensure that the optional arguments are properly specified and to avoid accidental positional matching of arguments.

• Other information:

• This PR closes Allow simulate_summary() to deal with finite populations #178.
• In the process of improving the documentation, the "specifying the generation time" subsection of simulate_chains() was changed to a section to ensure that it was not inherited in the process of reusing other sections in simulate_summary().
• The NEWS will be updated at the time of release and will highlight the features of {epichains} and its differences with {bpmodels}.

[codecov-commenter]

Codecov Report

All modified and coverable lines are covered by tests ✅

Comparison is base (72b23d4) 99.43% compared to head (7715a52) 99.45%.

❗ Current head 7715a52 differs from pull request most recent head 1b7ad5f. Consider uploading reports for the commit 1b7ad5f to get more accurate results

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #195      +/-   ##
==========================================
+ Coverage   99.43%   99.45%   +0.02%     
==========================================
  Files           8        8              
  Lines         529      550      +21     
==========================================
+ Hits          526      547      +21     
  Misses          3        3              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.