Improve documentation

[dodu94]

fix #519
fix #463

• Split the documentation tab into "benchmark" and "about"
• moved utilities to the "usage" tab
• moved the webapp doc to JADE doc
• specified in insert benchmark section the possibility to make a benchmark available in the webapp

Summary by CodeRabbit

Documentation

• Documentation
  • Reorganized benchmarks documentation with dedicated sections for computational and experimental benchmarks, including overview tables
  • Added WebApp documentation for visualizing JADE results and configuring benchmark JSON files
  • Created comprehensive developer guides for adding benchmarks, transport codes, and benchmark configurations
  • Restructured main documentation navigation for improved organization and discoverability
  • Updated repository links and removed outdated references

[coderabbitai]

Warning

Rate limit exceeded

@dodu94 has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 53 minutes and 31 seconds before requesting another review.

You’ve run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 36290ac2-5532-41c9-a43b-41657682125b

📥 Commits

Reviewing files that changed from the base of the PR and between 4b32b53 and dd02002.

📒 Files selected for processing (1)

• docs/source/dev/dev_idx.rst

Walkthrough

This PR restructures the JADE Sphinx documentation by elevating Benchmarks to top-level navigation, reorganizing the developer guide with new WebApp subsection, creating comprehensive add-benchmark workflow documentation, and consolidating About/publications content. The old flat documentation/benchmarks.rst structure is removed.

Changes

Documentation Structure and Navigation Reorganization

Layer / File(s)	Summary
Root navigation and About content restructuring docs/source/index.rst, docs/source/about/publications.rst	Root toctree updated to move benchmarks to top-level entry (benchmarks/benchmark_idx) and About publications link, with old documentation/docu_idx removed. Version header removed. Publications page title simplified.
Benchmarks section creation docs/source/benchmarks/benchmark_idx.rst, docs/source/benchmarks/overview.rst, docs/source/benchmarks/computational.rst, docs/source/benchmarks/experimental.rst	New top-level Benchmarks section with index page linking to overview (sources and CSV tables), computational benchmarks (assembled via includes), and experimental benchmarks. Replaces old documentation/benchmarks.rst structure.
Developer guide reorganization with WebApp subsection docs/source/dev/dev_idx.rst, docs/source/dev/webapp.rst, docs/source/dev/insertbenchmarks.rst	dev_idx.rst reorganized into topic-grouped toctrees (General information, Add a new benchmark, Existing and new plots, Add a new transport code, WebApp). New webapp.rst describes benchmark JSON configuration structure and tally definitions. insertbenchmarks.rst updated with guidance to add WebApp support for new benchmarks.
Add benchmark workflow documentation docs/source/dev/add_benchmark/where_inputs.rst, docs/source/dev/add_benchmark/raw_cfg.rst, docs/source/dev/add_benchmark/excel_cfg.rst, docs/source/dev/add_benchmark/atlas_cfg.rst	Four subsections document benchmark input placement (where_inputs), raw YAML configuration including tally modifiers and concatenation (raw_cfg), Excel post-processing configuration (excel_cfg), and atlas plotting configuration (atlas_cfg). Each includes field specifications, examples, and developer extension guidance.
Usage documentation and minor fixes docs/source/usage/usage_idx.rst, docs/source/dev/architecture_overview.rst, docs/source/usage/installation.rst, docs/source/nutshell.rst	usage_idx.rst expanded with JADE engine/ecosystem clarification and three team repository links; utilities entry added to toctree. architecture_overview.rst JADE-WEB-APP link corrected. installation.rst OpenMC warning generalized. nutshell.rst updated to reference JADE-V-V/JADE repo and removed contributor list reference.

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• JADE-V-V/JADE#446: Both PRs restructure/update the JADE benchmark documentation overview—this main PR creates the new docs/source/benchmarks/* Sphinx pages and removes docs/source/documentation/benchmarks.rst, while #446 directly revises that old structure.

• JADE-V-V/JADE#472: Both PRs update documentation for the ISIS-800MeV-C benchmark—Adding_ISIS_bech #472 adds/edits the benchmark description file, while this PR restructures benchmarks docs to include that same file under the new docs/source/benchmarks/experimental.rst.

• JADE-V-V/JADE#462: This PR builds on #462's earlier edits to the benchmarks documentation area by completing the restructure from flat docs/source/documentation/benchmarks.rst to the new hierarchical docs/source/benchmarks/* structure.

Suggested reviewers

• alexvalentine94

Poem

📚 A rabbit hops through docs with care,
Benchmarks and WebApp now laid bare,
Developer guides in sections neat,
The docs restructure: complete! 🐰

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Title check	❓ Inconclusive	The title "Improve documentation" is vague and generic, using non-descriptive language that doesn't convey the specific nature of the documentation restructuring.	Consider a more specific title such as "Reorganize documentation structure and move WebApp docs" to clearly indicate the main changes.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Linked Issues check	✅ Passed	All objectives from #519 and #463 are addressed: benchmarks overview tables were updated, WebApp documentation was moved into main JADE docs, and benchmark addition steps were documented.
Out of Scope Changes check	✅ Passed	All changes are focused on documentation restructuring and content organization aligned with the linked issues; no unrelated code changes detected.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch improve-documentation

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
see 2 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[coderabbitai]

Actionable comments posted: 4

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/source/about/about_idx.rst`:
- Line 1: The Sphinx target label "benchmarks" is duplicated and should be
renamed to a unique label (e.g., "about_benchmarks" or "benchmarks_about") to
avoid :ref: resolution conflicts; update the label in this file (the top
directive currently ".. _benchmarks:") to the new unique name and search/update
any cross-references that point to "benchmarks" to use the new label so all
links resolve correctly.
- Around line 3-5: Rename the page heading from "Benchmarks" to "About" in the
about_idx RST file (the page wired as about/about_idx) by replacing both the
overline and the title text so the visual header reads "About" and ensure the
underline/overline length matches the new title length (adjust the row of #
characters accordingly) so the reStructuredText heading stays valid.

In `@docs/source/dev/webapp.rst`:
- Line 95: Fix the typo in the user-facing docs by replacing the word
“benchmarls” with “benchmarks” in the sentence that currently reads "forces the
plot always to be C/E (ratio). This is sometimes useful for some of the
experimental benchmarls where absolute values are not that important." Update
that exact phrase so the docs display the correct spelling "benchmarks".
- Line 76: The "grouped_bar options" link text is malformed and may 404; update
the link target so it matches Plotly's correct URL pattern used elsewhere —
replace the existing `grouped_bar options
<https://plotly.com/python-api-reference/generated/plotly.express.bar>`_ anchor
with the correct Plotly reference URL for grouped bar options (the same style
used for other Plotly links) so the `grouped_bar options` link points to the
proper plotly.express.bar documentation page.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: ad355923-3672-4334-8d4f-93ca23055ae3

📥 Commits

Reviewing files that changed from the base of the PR and between 314efef and 2740149.

⛔ Files ignored due to path filters (4)

• docs/source/benchmarks/computational_overview.csv is excluded by !**/*.csv
• docs/source/benchmarks/exp_overview.csv is excluded by !**/*.csv
• docs/source/documentation/computational_overview.csv is excluded by !**/*.csv
• docs/source/documentation/exp_overview.csv is excluded by !**/*.csv

📒 Files selected for processing (43)

• docs/source/about/LICENSE.rst
• docs/source/about/about_idx.rst
• docs/source/about/contributors.rst
• docs/source/about/publications.rst
• docs/source/benchmarks/benchdesc/ISIS-800MeV-C.rst
• docs/source/benchmarks/benchdesc/aspis/aspis-fe88.rst
• docs/source/benchmarks/benchdesc/aspis/aspis-pca-replica.rst
• docs/source/benchmarks/benchdesc/cmodel.rst
• docs/source/benchmarks/benchdesc/fng/fng-blk.rst
• docs/source/benchmarks/benchdesc/fng/fng-hcpb.rst
• docs/source/benchmarks/benchdesc/fng/fng-sddr.rst
• docs/source/benchmarks/benchdesc/fng/fng-sic.rst
• docs/source/benchmarks/benchdesc/fng/fng-ss.rst
• docs/source/benchmarks/benchdesc/fng/fng-w.rst
• docs/source/benchmarks/benchdesc/fng/tud-fng.rst
• docs/source/benchmarks/benchdesc/fng/tud-w.rst
• docs/source/benchmarks/benchdesc/fns-tof.rst
• docs/source/benchmarks/benchdesc/icbep_disclaimer.rst
• docs/source/benchmarks/benchdesc/ippe/ippe_cf.rst
• docs/source/benchmarks/benchdesc/ippe/ippe_dt.rst
• docs/source/benchmarks/benchdesc/iter1d.rst
• docs/source/benchmarks/benchdesc/itercylSDDR.rst
• docs/source/benchmarks/benchdesc/oktavian.rst
• docs/source/benchmarks/benchdesc/rcr/rcr-fe+ni.rst
• docs/source/benchmarks/benchdesc/rcr/rcr-ss.rst
• docs/source/benchmarks/benchdesc/simptokamak.rst
• docs/source/benchmarks/benchdesc/sinbad_disclaimer.rst
• docs/source/benchmarks/benchdesc/sphere.rst
• docs/source/benchmarks/benchdesc/sphereSDDR.rst
• docs/source/benchmarks/benchdesc/tbm.rst
• docs/source/benchmarks/benchdesc/tiara.rst
• docs/source/benchmarks/benchdesc/tud-fe.rst
• docs/source/benchmarks/benchmark_idx.rst
• docs/source/benchmarks/computational.rst
• docs/source/benchmarks/experimental.rst
• docs/source/benchmarks/overview.rst
• docs/source/dev/dev_idx.rst
• docs/source/dev/insertbenchmarks.rst
• docs/source/dev/webapp.rst
• docs/source/documentation/benchmarks.rst
• docs/source/documentation/docu_idx.rst
• docs/source/index.rst
• docs/source/usage/usage_idx.rst

💤 Files with no reviewable changes (2)

• docs/source/documentation/docu_idx.rst
• docs/source/documentation/benchmarks.rst

[coderabbitai]

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Fix the grouped bar Plotly reference URL.

The grouped_bar options link appears malformed compared to the other Plotly links and may 404 in some contexts.

Suggested diff

-    * `grouped_bar options <https://plotly.com/python-api-reference/generated/plotly.express.bar>`_ from plotly API reference.
+    * `grouped_bar options <https://plotly.com/python-api-reference/generated/plotly.express.bar.html>`_ from plotly API reference.

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	* `grouped_bar options <https://plotly.com/python-api-reference/generated/plotly.express.bar>`_ from plotly API reference.
	* `grouped_bar options <https://plotly.com/python-api-reference/generated/plotly.express.bar.html>`_ from plotly API reference.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/source/dev/webapp.rst` at line 76, The "grouped_bar options" link text
is malformed and may 404; update the link target so it matches Plotly's correct
URL pattern used elsewhere — replace the existing `grouped_bar options
<https://plotly.com/python-api-reference/generated/plotly.express.bar>`_ anchor
with the correct Plotly reference URL for grouped bar options (the same style
used for other Plotly links) so the `grouped_bar options` link points to the
proper plotly.express.bar documentation page.

[alexvalentine94]

One minor comment to consider.

[alexvalentine94]

Did we also add to the docs that this table should be updated by the user.