Document the draft workflow from source add to build - #73
Merged
Merged
Conversation
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
1 participant
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.
The documentation describes the spec engine (docs/source/spec.md) and the question format, and the command line reference lists every subcommand, but no page explains the workflow those commands form: freeze a document, fill the draft by spec or by commands, validate, build. A reader who has the four modules in front of them cannot tell in which order to use them or why a draft has a log.
Write one page, docs/source/drafts.md, in the toctree after quickstart and before spec, that walks one small document through the workflow:
in2lambda source add sheet.texand whatsheet.draft.jsoncontains (blocks, line ranges, the hash);in2lambda source show;in2lambda spec runand the coverage report; the range commands (draft question add,part add,question solution,mark ignore,split block) with the four layers and the provenance each writes;draft field replace;draft replay;in2lambda validatewith an example report showing an error and a warning;in2lambda buildandrender. Show the actual command output, as the quickstart does. Cross-reference the spec page and the format page instead of repeating them.Every sentence follows the writing-prose-here skill. Done when the page builds in the Sphinx site, every command shown runs as printed against a fixture in the repository, and a reviewer reading the page alone can drive a document from source to zip.
Workbench ticket t45.