{ "__type": "IngestedDoc", "__tag": 4010, "_content": {}, "_ordered_sections": [], "item_file": null, "item_line": null, "item_type": null, "aliases": [], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "see_also": [], "signature": null, "references": null, "qa": "specimens:blocks", "arbitrary": [ { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Block-level structure: paragraphs, the three kinds of list, block quotes, literal and code blocks, doctests, and transitions." } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Block constructs" } ], "level": 0, "target": "specimen-blocks" }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "A paragraph is any run of text separated from its neighbours by a blank line." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This is a second paragraph. Paragraphs are the default container — most other block constructs are introduced by a marker (a bullet, a directive, an indent), but plain prose needs no ceremony." } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Paragraphs" } ], "level": 1, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "First item." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Second item, which is long enough to wrap onto a second line so you can see how continuation text aligns under the bullet rather than under the marker." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Third item." } ] } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Lists nest by indentation:" } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Top-level item." } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Nested item A." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Nested item B." } ] } ] } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Back to the top level." } ] } ] } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Bullet lists" } ], "level": 1, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "BulletList", "__tag": 4053, "ordered": true, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "First." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Second." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Third." } ] } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Auto-numbered lists use " }, { "__type": "InlineCode", "__tag": 4051, "value": "#" }, { "__type": "Text", "__tag": 4046, "value": ":" } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": true, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Counts from one." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Without you tracking the numbers." } ] } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Nested enumeration mixes letters and digits:" } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": true, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Step one." } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": true, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Sub-step." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Another sub-step." } ] } ] } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Step two." } ] } ] } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Enumerated lists" } ], "level": 1, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "A definition list pairs a term with its definition:" } ] }, { "__type": "DefList", "__tag": 4033, "children": [ { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "DocBundle" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The self-contained intermediate representation produced by " }, { "__type": "InlineCode", "__tag": 4051, "value": "papyri gen" }, { "__type": "Text", "__tag": 4046, "value": " for a single project at a single version." } ] } ] }, { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "ingest" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The TypeScript pipeline that wires uploaded bundles into the cross-linked graph served by the viewer." } ] } ] }, { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "graphstore" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "A derived cache. The only authoritative IR is the raw " }, { "__type": "InlineCode", "__tag": 4051, "value": ".papyri.gz" }, { "__type": "Text", "__tag": 4046, "value": " archive; the graphstore can always be rebuilt by re-ingesting it." } ] } ] } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Definition lists" } ], "level": 1, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Field lists are " }, { "__type": "InlineCode", "__tag": 4051, "value": ":name: value" }, { "__type": "Text", "__tag": 4046, "value": " pairs, useful for compact metadata:" } ] }, { "__type": "FieldList", "__tag": 4035, "children": [ { "__type": "FieldListItem", "__tag": 4036, "name": [ { "__type": "Text", "__tag": 4046, "value": "Author" } ], "body": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The papyri contributors" } ] } ] }, { "__type": "FieldListItem", "__tag": 4036, "name": [ { "__type": "Text", "__tag": 4046, "value": "Status" } ], "body": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Specimen" } ] } ] }, { "__type": "FieldListItem", "__tag": 4036, "name": [ { "__type": "Text", "__tag": 4046, "value": "Encoding" } ], "body": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "JSON in the bundle directory, CBOR in the " }, { "__type": "InlineCode", "__tag": 4051, "value": ".papyri" }, { "__type": "Text", "__tag": 4046, "value": " artifact" } ] } ] } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Field lists" } ], "level": 1, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "A block quote is simply an indented block of text:" } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Documentation should be generated once and rendered many times. Splitting the two halves is the whole point of papyri." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "A block quote can span multiple paragraphs, and the indentation is what marks it as quoted." } ] } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Block quotes" } ], "level": 1, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "A double colon at the end of a paragraph introduces a literal block, rendered verbatim with no markup processing " } ] }, { "__type": "Code", "__tag": 4050, "value": "This text is shown exactly as written.\n Indentation is preserved.\n*asterisks* are literal, not emphasis.", "execution_status": null } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Literal blocks" } ], "level": 1, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The " }, { "__type": "InlineCode", "__tag": 4051, "value": "code-block" }, { "__type": "Text", "__tag": 4046, "value": " directive (and its aliases " }, { "__type": "InlineCode", "__tag": 4051, "value": "code" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineCode", "__tag": 4051, "value": "sourcecode" }, { "__type": "Text", "__tag": 4046, "value": ") takes an explicit language for syntax highlighting:" } ] }, { "__type": "Code", "__tag": 4050, "value": "from papyri.gen import Gen\n\ndef build(config_path: str) -> None:\n gen = Gen(config_path)\n gen.collect_narrative_docs()", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "A TOML snippet, highlighted as TOML:" } ] }, { "__type": "Code", "__tag": 4050, "value": "[global]\nmodule = \"mylib\"\ndocs_path = \"docs\"", "execution_status": null } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Code blocks" } ], "level": 1, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Doctest blocks begin with the " }, { "__type": "InlineCode", "__tag": 4051, "value": ">>>" }, { "__type": "Text", "__tag": 4046, "value": " prompt and are executed at gen time when " }, { "__type": "InlineCode", "__tag": 4051, "value": "execute_doctests" }, { "__type": "Text", "__tag": 4046, "value": " is enabled, so the captured output is part of the IR " } ] }, { "__type": "Code", "__tag": 4050, "value": ">>> 1 + 1\n2\n>>> \"papyri\".upper()\n'PAPYRI'", "execution_status": null } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Doctests" } ], "level": 1, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "A transition is a horizontal rule between blocks, written as a line of punctuation:" } ] }, { "__type": "ThematicBreak", "__tag": 4019 }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "It separates content without introducing a new section heading." } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Transitions" } ], "level": 1, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Strong", "__tag": 4048, "children": [ { "__type": "Text", "__tag": 4046, "value": "Line blocks" } ] }, { "__type": "Text", "__tag": 4046, "value": " (lines prefixed with " }, { "__type": "InlineCode", "__tag": 4051, "value": "|" }, { "__type": "Text", "__tag": 4046, "value": " to preserve line breaks) are currently dropped with a warning — do not rely on them." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Strong", "__tag": 4048, "children": [ { "__type": "Text", "__tag": 4046, "value": "Block-quote attributions" } ] }, { "__type": "Text", "__tag": 4046, "value": " (a " }, { "__type": "InlineCode", "__tag": 4051, "value": "-- Author" }, { "__type": "Text", "__tag": 4046, "value": " line at the end of a quote) are not implemented and will fail the whole document; write the attribution as ordinary text instead." } ] } ] } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Not supported" } ], "level": 1, "target": null } ], "local_refs": [] }