Skip to content

docs(tutorials): callout working_dir convention for artifact tasks#1300

Open
ppcvote wants to merge 1 commit into
usnistgov:devfrom
ppcvote:docs/working-dir-callout
Open

docs(tutorials): callout working_dir convention for artifact tasks#1300
ppcvote wants to merge 1 commit into
usnistgov:devfrom
ppcvote:docs/working-dir-callout

Conversation

@ppcvote

@ppcvote ppcvote commented Jun 1, 2026

Copy link
Copy Markdown

Summary

Adds an .. important:: admonition to Step 1 of the Saving Artifacts tutorial (docs/source/tutorials/essential_workflows/part-5.rst) explaining that file paths inside serialize and deserialize must be built relative to the working_dir argument that Dioptra passes in.

The existing example code (docs/source/documentation_code/plugins/essential_workflows_tutorial/artifacts.py) already follows this convention — but the surrounding prose never explains why, which is the gap the issue reports:

Not constructing paths using working_dir as a base can lead to unexpected behaviors where an artifact fails to load, but it's unclear why.

The new admonition:

  • States the rule directly (paths must be built from working_dir).
  • Names the canonical patterns (working_dir / name in serialize, working_dir / path in deserialize) and ties them back to the example block on the same page.
  • Describes the failure mode (artifact appears to save, but is untracked and deserialize raises a misleading file not found later in the pipeline).

Also adds ppcvote to CONTRIBUTORS.md per CONTRIBUTING.md.

Notes

  • Docs-only change. No code, no test surface, no build-config impact.
  • Placement is right after the existing Step 1 .. note:: block so the rule reads as a follow-on to the serialize/deserialize description.
  • Used .. important:: (rather than another .. note::) to give the warning visual weight without escalating to .. warning::, since this is a get-this-right detail rather than a security/data-loss caveat.
  • Followed the dev-branch + commit-style conventions in CONTRIBUTING.md and COMMIT_STYLE_GUIDE.md.

Closes #1267

Add an `.. important::` admonition to the Saving Artifacts tutorial
explaining that file paths inside `serialize` and `deserialize` must be
constructed relative to the `working_dir` argument. The existing example
code already follows this convention, but the surrounding prose does
not call out *why*, so a user who writes to an absolute path sees the
artifact appear to save and then later fails to deserialize with a
generic "file not found" error.

Closes usnistgov#1267
@ppcvote

ppcvote commented Jun 13, 2026

Copy link
Copy Markdown
Author

Hi @jkglasbrenner — this docs-only PR closes #1267 (the working_dir convention callout you flagged). It's a single admonition added to part-5.rst (+8 lines) with no code changes — the prose just names the pattern your own example code already demonstrates, so no logic review needed. Mergeable, no conflicts, targets dev per CONTRIBUTING. (The CONTRIBUTORS.md entry is required per CONTRIBUTING.md.) Let me know if any adjustment would help. Thanks!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant