docs(tutorials): callout working_dir convention for artifact tasks#1300
Open
ppcvote wants to merge 1 commit into
Open
docs(tutorials): callout working_dir convention for artifact tasks#1300ppcvote wants to merge 1 commit into
ppcvote wants to merge 1 commit into
Conversation
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
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! |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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 insideserializeanddeserializemust be built relative to theworking_dirargument 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:The new admonition:
working_dir).working_dir / nameinserialize,working_dir / pathindeserialize) and ties them back to the example block on the same page.Also adds
ppcvotetoCONTRIBUTORS.mdper CONTRIBUTING.md.Notes
.. note::block so the rule reads as a follow-on to the serialize/deserialize description... 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.CONTRIBUTING.mdandCOMMIT_STYLE_GUIDE.md.Closes #1267