Differences from a Sphinx build¶

The ubCode preview is built for instant feedback while you type: it parses and renders your document on every keystroke, so it deliberately skips the slower, whole-project transforms that a full sphinx-build runs at the end. This page is the honest register of the resulting user-visible differences, so you can trust what you see and know when to reach for a real build.

Every entry below describes the Rendered preview mode (in Structural mode every directive and role renders as a uniform placeholder; see Authoring). Unless a status line says otherwise, none of these differences affect the correctness of background indexing or diagnostics — they change only what the preview panel displays.

The main entries follow the same shape — what you write, what the preview shows, what a Sphinx build does, and a short status note; smaller differences are grouped into bullet lists.

Not yet rendered¶

These constructs are recognised and shown as self-describing placeholders, but the transform that gives them their final form does not run in the preview yet.

Substitutions |name|

The preview shows the name between bars as a literal chip, never expanded — even for your own replace:: definitions.

A Sphinx build expands each reference to its substitution text: the configured version or release string, today’s date, or your replacement text.

Status — substitution expansion is not part of the preview’s fast pass. Indexing and diagnostics are unaffected.

toctree

You write .. toctree:: with options such as :maxdepth: and a list of document names.

The preview shows a generic directive placeholder listing the directive name, its options, and the raw document list. No document tree or navigation is produced.

A Sphinx build assembles the document hierarchy and renders it as nested navigation links.

Status — the document tree is a whole-project transform the preview does not run. toctree is a known directive, so it raises no unknown-directive diagnostic.

Footnotes and citations

You write footnote and citation references such as [1]_, [#]_, or [CIT2002]_, with their matching definitions.

The preview shows each reference as a superscript label, but the label is not linked or resolved to its definition.

A Sphinx build numbers auto footnotes, resolves each reference, and renders bidirectional links between reference and definition.

Status — reference resolution is a whole-document transform the preview does not run. Indexing and diagnostics are unaffected.

Math

You write a formula with the :math: role or a .. math:: block.

The preview shows the raw source, not typeset.

A Sphinx build typesets the math (via MathJax, KaTeX, or images).

Status — no math typesetting engine is bundled with the preview yet. Indexing and diagnostics are unaffected.

Document structure¶

Docinfo

You write a document that opens with a bibliographic field list (:Author:, :Version:, :Date:, and so on).

The preview shows a plain field list, the same as any field list appearing mid-document.

A Sphinx build turns the leading field list into a bibliographic docinfo table.

Status — the preview does not model docinfo. Indexing and diagnostics are unaffected.

rst_prolog / rst_epilog

You write content in rst_prolog or rst_epilog (in your parsing configuration).

The preview shows the prologue and epilogue spliced as their own blocks at the very start and end of each RST document, at the document root — not merged into the document’s section structure. A prologue that begins with a heading never swallows the rest of the document. State set there, such as a default role, still applies to the whole document. A malformed prolog is silently not shown.

A Sphinx build appends the epilogue text inside the document’s trailing section, and a prologue that opens a section can absorb the whole document.

Status — the splice is structural rather than a raw text concatenation. Indexing and diagnostics are unaffected by where the splice lands, though state set in a prologue affects the preview only — as noted for included files below.

Included files¶

.. include:: expands inline in the Rendered preview. A few things differ from how a Sphinx build splices the same file textually:

State set inside an included file — a .. default-role::, for example — is scoped to that file in the preview. A Sphinx build lets that state leak into the rest of the host document.
A section heading in an included file that uses the same underline level as the host nests one level deeper in the preview than in a Sphinx build.
Clicking inside spliced content does not jump to the included file; sync-scroll maps spliced content back to the .. include:: line in the host document.
Include options the preview does not support are flagged with a diagnostic and ignored; the file is still spliced in.

Note

State changes made inside an .. include:: (or in rst_prolog) affect the preview but not the diagnostics the background index produces: the index reads each file on its own, so a default role set inside an included fragment is not reflected in the diagnostics reported for the host document. This is one of the few places where the preview and the background index can legitimately disagree.

Needs and variants¶

Need directives render as need cards. How a card looks compared with a Sphinx-Needs build:

A hydrated card lists the fields you authored plus any added by needextend — not the full set of config-default fields a Sphinx-Needs build can show in layouts that list every field.
Cards and their links refresh after each background indexing pass completes — a bounded refresh, not one per keystroke.
A falsy .. if:: block stays visible but collapsed and greyed out, labelled with its condition; a Sphinx-Needs build omits the block entirely.
A need referenced only inside a non-indexed include fragment (for example an extensionless or excluded file) keeps its placeholder chip, because the background index does not look inside such fragments.

Diagrams¶

Mermaid and PlantUML diagram directives render, with a few option differences:

:width: and :height: size the diagram container in the preview (a bare number is treated as pixels). A Sphinx build drops these options for Mermaid diagrams.
:alt:, :scale:, :config:, :title:, and :zoom: are parsed but not applied.
Caption text is rendered as plain text; inline markup inside a caption is not parsed.

Code blocks¶

code-block (with its aliases sourcecode and code), :: literal blocks, and .. highlight:: render with syntax highlighting, with a few differences from a Sphinx build:

The preview highlights client-side with a bundled set of common languages, not Pygments — colours differ from your Sphinx theme, and a language Pygments knows but the preview does not is shown as plain preformatted text (never mangled).
:linenos:, :lineno-start:, and :emphasize-lines: are parsed but not applied — no line numbers or emphasised lines yet.
:dedent: and :force: are parsed but not applied.
:caption: text is rendered as plain text above the block; inline markup inside a caption is not parsed (as for diagram captions above).
An argument-less code-block (or a plain :: block) with no .. highlight:: language and no configured highlight_language stays unhighlighted; a Sphinx build falls back to highlighting it as Python (its default).

Structure and inline detail¶

Some finer points of block and inline rendering differ from a Sphinx build:

Directive titles and arguments are not inline-parsed: markup in an admonition title, a version-marker line, or centered appears literally.
The body of parsed-literal shows inline markup literally.
Nested line blocks render flattened rather than progressively indented.
.. container:: ins and .. container:: del render as plain containers — insertion and deletion semantics are not applied.
Attribution lines (-- author) in epigraph, highlights, and pull-quote stay plain paragraphs rather than becoming attributions.
An unsupported option on a structural block makes the whole directive fall back to the generic placeholder.

Unknown directives and roles¶

Unknown directives

You write a directive ubCode does not recognise, such as .. wibble::.

The preview shows a generic directive placeholder.

A Sphinx build reports an error and typically drops or marks the construct.

Status — unknown directives also raise a configurable lint diagnostic. Register the directive with extend_directives, or silence it with ignore_directives, in your parsing configuration; see Linting.

Unknown roles

You write text marked up with an inline role ubCode does not recognise, such as a :wibble: role.

The preview shows a placeholder chip naming the role and its content.

A Sphinx build reports an error and typically drops or marks the construct.

Status — the chip is self-describing, so you can spot the unrecognised role at a glance.

Images¶

A local image whose file lives outside your workspace folder does not load in the preview; the preview can only read files within the workspace.
Remote images referenced by an https:// URL load directly.

Closing the gap¶

The preview grows release by release: ubCode actively closes the gap with Sphinx and Sphinx-Needs, and the constructs shown as placeholders today — substitutions, toctree, math, and resolved footnotes — are tracked on the Roadmap. When you need the final, fully-transformed output, run a full sphinx-build.