Unsupported syntax

These are the constructs a Sphinx project can write that ubCode does not render, each with what to write instead.

A directive ubCode recognises but has no renderer for is drawn as a placeholder, a labelled frame showing its name, options and body, in the preview and in both builds, and ubc build html and ubc build pdf report it once per name (build.directive_unhandled, build.pdf_directive_unhandled). A directive it does not recognise at all is reported as block.directive_unknown, and a role it has no renderer for is drawn as a chip and reported as build.role_unhandled.

Every other directive and role ubCode renders is shown on the Writing pages, and this page is checked against ubCode’s own list of what it renders, so a row leaves the table when its construct is supported.

API documentation

Construct	Instead
.. auto*:: — .. automodule::, .. autoclass:: and the other autodoc directives	ubCode does not import or run your code. Build the API reference with Sphinx, and link to it through intersphinx.
.. py:*::, .. c:*::, .. cpp:*::, .. js:*::, .. rst:*::, .. describe::, .. object::, .. class:: — the object descriptions	Describe the object in a definition list or a field list. (.. class:: is the Python domain’s here, as in a Sphinx build; to give a block a class, write .. rst-class::.)
:py:*:, :c:*:, :cpp:*:, :js:*:, :rst:*: — references to those objects	Put a label on the description and refer to it with :ref:.
.. program::, .. option::, .. cmdoption::, .. productionlist::, and the :option:, :token: and :keyword: references	Write a command’s options as an option list, and refer to them by a label with :ref:.

Numbering

Construct	Instead
.. sectnum::, .. section-numbering::	Number the headings in their titles.
The toctree’s :numbered: option	Number the headings in their titles. The option is accepted and ignored, with no finding: the headings print unnumbered.
Sphinx’s numfig setting (figure, table and code-block numbers)	Give the caption its number yourself. ubCode has no such setting, so captions print unnumbered, with no finding.
.. target-notes::	Write the links you want listed as footnotes.
:numref:, :eq:, :math:numref:	Refer to the figure, table or equation’s label with :ref:, giving the link text yourself.

Diagrams

Construct	Instead
.. graphviz::, .. graph::, .. digraph::	Draw it with mermaid, or with PlantUML’s uml (see Diagrams).

Sphinx-Needs

Construct	Instead
.. needservice::	Export the service’s data to a needs.json file and import it with needimport (see What works inside imported need content); ubCode does not reach out to services while it builds.

sphinx-design

Construct	Instead
.. tab-set-code::	A tab-set with one code-block in each tab-item.
.. card-carousel::	A grid of cards.
.. article-info::	Write the author and date as text.
:fa:, :fab:, :far:, :fas:, :material-*: — the icon-font roles	The :octicon: role, which ubCode renders.

Other constructs

Construct	Instead
:cve:, :cwe:	A hyperlink to the entry.
.. restructuredtext-test-directive::	Nothing: docutils registers it for its own tests.

MyST extensions

Three of MyST-Parser’s extensions are not implemented: naming one in the parsing configuration reports config.extension_unimplemented, and its syntax renders as written.

Extension	Instead
substitution (and its {sub-ref} role)	Write the text out, or keep the page in reStructuredText, whose replace substitutions render.
linkify	Enable gfm_autolink, which links bare URLs in both ubCode and MyST-Parser.
html_admonition	Write the admonition as a directive, such as {note} or {admonition}.