Skip to content

Documentation update - #177

Merged
schote merged 31 commits into
mainfrom
docu
Nov 10, 2026
Merged

schote merged 31 commits into
mainfrom
docu

Conversation

@schote

@schote schote commented Oct 9, 2026 •

Copy link
Copy Markdown
Owner

Migrate documentation from Sphinx to MkDocs

This PR replaces the Sphinx documentation with MkDocs (Material theme) and revises the content.

Preview

https://schote.github.io/nexus-console/pr-177/

The preview is rebuilt on every push to this PR and removed when the PR is closed.
The live documentation at https://schote.github.io/nexus-console/ remains the Sphinx version until this PR is merged.

What changed

  • Tooling: MkDocs Material instead of Sphinx; the API reference is generated from the docstrings (mkdocstrings).
  • Structure: Setup · System guide (overview, console hardware, device configuration, sequence calculation, acquisition, postprocessing) · Examples · API reference · References.
  • Single source: the landing page reuses the summary, citation and acknowledgments of the README.
  • Citation: CITATION.cff enables GitHub's "Cite this repository" button; README with DOI badge and BibTeX.
  • Deployment: versioned with mike: main is deployed as latest, each pull request gets its own preview version.

How to review

  • Read the preview. Please check in particular that descriptions match the code and that the pages are understandable without prior knowledge of the code base.
  • Comment directly in this PR and name the page and section, e.g. System guide → Acquisition, step 9.
  • To build the docs locally: pip install -e ".[docs-mkdocs]", then mkdocs serve.

Checklist

  • Loopback hardware test passed (run python tests/hardware/loopback.py -d <device_config.yaml>) -> not necessary, only docstrings and /docs were updated
  • Tests added or updated (if necessary)
  • Documentation updated (user guide, API docs, port tables, etc.)
  • Examples updated (if necessary)

@schote schote self-assigned this Oct 9, 2026
@github-actions

github-actions Bot commented Oct 9, 2026 •

Copy link
Copy Markdown

Coverage

Coverage Report
FileStmtsMissCoverMissing
src/console
   __init__.py10190%11
src/console/interfaces
   acquisition_data.py1232580%101–104, 115–116, 134–135, 150–153, 186–187, 216–217, 221–227, 244–245, 256, 260, 278
   acquisition_parameter.py107496%130, 167, 183, 212
   device_configuration.py93298%107, 113
   dimensions.py962277%43–44, 65–66, 69, 77, 87, 93, 99, 105, 111–113, 123–125, 135–137, 147–149
   rx_data.py1374567%98–102, 106–113, 123–129, 140–147, 151–155, 172, 181, 183, 198, 206–211, 219, 227, 230, 233
src/console/pulseq_interpreter
   sequence_provider.py2482789%103, 252–253, 349–350, 460, 510–511, 515, 586, 612–613, 623–624, 629, 638, 642, 649–662
src/console/service
   acquisition_manager.py28280%2–71
   start_manager.py35350%2–118
src/console/spcm_control
   abstract_device.py108992%12, 34, 36, 38, 40, 44, 126, 174–175
   acquisition_control.py1831830%3–403
   rx_processor.py46460%9–125
src/console/utilities
   json_encoder.py10550%22–26
   load_configuration.py20670%18–20, 28–30
   plot.py531670%31–32, 80–98
src/console/utilities/data
   mrd_helper.py43881%37, 43, 49, 52, 60, 63, 68, 71
   write_acquisition_to_mrd.py54591%93–94, 118, 136, 141
src/console/utilities/sequences/calibration
   fid_tx_adjust.py23196%70
   se_tx_adjust.py30293%66–68
src/console/utilities/sequences/spectrometry
   fid.py15193%49
   se_spectrum.py26292%55, 111
src/console/utilities/sequences/tse
   tse_3d.py2387170%130–131, 133–134, 136–137, 144–145, 147–149, 151–154, 165–168, 173–176, 183–194, 211, 236–240, 246, 277, 340–357, 364–365, 432, 435–447, 557–568
TOTAL188454471% 
Tests Skipped Failures Errors Time
206 0 💤 0 ❌ 0 🔥 15.840s ⏱️

@schote
schote marked this pull request as ready for review October 29, 2026 16:38
@schote schote added the type: documentation Improvements or additions to documentation label Oct 29, 2026
@schote
schote requested a review from h3lg3 October 30, 2026 07:11
Comment thread docs/setup/hardware-setup.md Resolved
Comment thread docs/setup/first-acquisition.md Resolved
Comment thread docs/setup/first-acquisition.md Resolved
Comment thread docs/system/overview.md Resolved
Comment thread docs/system/configuration.md Resolved
Comment thread docs/system/configuration.md Resolved
Comment thread docs/system/postprocessing.md Resolved
Comment thread docs/system/postprocessing.md Resolved
Comment thread docs/examples/spin_echo.md Resolved
Comment thread docs/examples/spin_echo.md Resolved
Comment thread docs/examples/t2_measurement.md Resolved
Comment thread docs/examples/t2_measurement.md Resolved
Comment thread docs/references.md Resolved
Comment thread examples/t2_measurement.py Resolved
@schote

schote commented Nov 9, 2026

Copy link
Copy Markdown
Owner Author
  • in postprocessing.md: "acquisition_time_stamp - Start of the gate in µs, relative to the start of the digitizer." Why relative to the start of the digitizer? Commonly this is the time since midnight or some other daily reference point.

When using the gated acquisition mode, the digitizer module stores two timestamps per ADC gate, which are used to define the memory transfer. The format of these timestamps is "time since card operation start". The first time stamp is stored in the RxData object. In the RxData object I would leave it as is to prevent any unnecessary arithmetic when reading the data from the card. But for the ISMRMRD export, we could add it to a global acquisition time (the time when the card opertion starts).

@schote

schote commented Nov 9, 2026

Copy link
Copy Markdown
Owner Author

Under Setup: "MRI system is explained in the System overview." The link says "System overview" but redirects ro "System guide" in the tab bar at the top.

"System guide" is like a chapter and "System overview" the first section of it. I made the naming consistent and shortened it to "Overview".

@schote
schote requested review from ckolbPTB and h3lg3 November 9, 2026 16:39
Comment thread docs/system/sequence-calculation.md Resolved
@schote
schote merged commit 64e6ade into main Nov 10, 2026
8 checks passed
@schote
schote deleted the docu branch November 10, 2026 12:41
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

type: documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants