Compatibility with rustdoc

This document compares the rustdoc markdown syntax and features with those supported by this extension via myst-parser. It also provides an explanation of the various myst-parser extensions that enable this compatibility.

Markdown syntax

myst-parser and Rust’s markdown both target the CommonMark specification. However, Rust provides some additional features that are not part of the CommonMark specification. Almost all of these syntax extensions are supported by myst-parser. The Markdown usage sections lists all the extensions required.

To make the docstrings work with both rustdoc and this tool, the following changes may be required to existing docstrings:

Use double tilde (~~) only for strike-through.
Use a backslash in front of literal text enclosed in brackets (\[foo] instead of [foo]) to prevent it from being rendered as broken link.
Replace links that use Self::, self:: or super:: with the name of the type, value or macro. Links with crate:: in the target do not need to be updated.
Use explicit text for the hyperlink when using namespaces and disambiguators, as in [`Foo`](struct@Foo) instead of [`struct@Foo`].

The sections below cover any differences in syntax and extensions required to make docstrings work with both Rust and Sphinx.

Attrs block

The attrs_block extension is used to separate the sections within docstrings from the sections of the table of contents. Essentially, the markdown sections in the docstrings are handled separately from the sections of the page. See the warning in https://myst-parser.readthedocs.io/en/latest/syntax/organising_content.html#document-structure for details.

Colon-fencing

The colon_fence extensions allows using colons (:::) for fencing instead of the usual back-ticks. This is used when generating the docs so they can be rendered properly in other markdown compatible tools. Removing this extension will cause issues with the generated documentation. See https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#code-fences-using-colons for details.

Strikethrough

Enable the strikethrough extension for myst-parser in conf.py and use ~~ for strikethrough in the docstrings. Rust supports a single ~, but myst-parser does not. See https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#strikethrough for details.

Footnotes

Both Rust and myst-parser use the same syntax for footnotes, so they should work as is. See https://myst-parser.readthedocs.io/en/latest/syntax/typography.html#footnotes for details.

Tables

Both Rust and myst-parser target the GitHub markdown table syntax. It should work out of the box.

Tasks List

Enable the tasklist extension for myst-parser in conf.py. The syntax is the same with this extension enabled. See https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#task-lists for details.

Smart punctuation

Enable the smartquotes and replacements extensions for myst-parser in conf.py. This will enable smart punctuation similar to Rust’s markdown and some more. See https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#typography for details.

Warning blocks and admonitions

Rust uses a separate div class for this as described here. To support a similar syntax for admonitions, enable the html_admonition extension for myst-parser in conf.py. See https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#html-admonitions for details. There are some additional features supported by myst-parser compared to Rust.

myst-parser supports Sphinx admonition directives as described at https://myst-parser.readthedocs.io/en/latest/syntax/admonitions.html, but they will not be rendered by rustdoc.

rustdoc features

Missing docs warning

This extension does not check for missing documentation when executed. It will list any items that it discovers, even when there are no docs for them. The warning may be supported in future.

#[doc] attributes

Crate level doc attributes are not supported. Most crate level doc attributes deal with the publication of the HTML and executing doctests. If any of these attributes are present, they are ignored when extracting the docs. The behavior of some HTML attributes may be achieved via Sphinx configuration options and extensions.

Item level doc attributes are not supported at present, but future versions may support some of them. This section will be updated as support for various attributes is implemented.

Re-exports

Re-exports are supported similar to rustdoc, with some differences in behavior. The tool does not currently recognize rustdoc attributes like inline, hidden and noinline. So, inlining is done purely based on whether the item will be documented in its original location or in a re-exported location. Documentation for the re-export is combined with the documentation of the original item, if the item is inlined.

Intra-doc links

Intra-doc links are supported using all 4 syntax shown in the examples for Markdown only. However, using Self::, self:: and super:: in the link target is not supported. Link targets with crate:: are supported. (See Valid links section below.)

Currently, it is necessary to add a backslash (\) in front of a literal text that appears within brackets (\[foo] instead of [foo]). Otherwise, there will be a warning regarding unresolved references and the text will be rendered as a broken link. The backslash will remove this issue.

For reStructuredText, it is recommended to use the rust:any role as the default Sphinx role for references to support similar behavior. With that added to Sphinx configuration, references can simply be written as `ref`, without specifying the type of the reference.

Valid links

Rustdoc provides a rich syntax for valid links. However, this tool does not support any of those features, except link references beginning with crate:: and references to items with generic parameters.

Additionally, the tool cannot link to items outside of the crate(s) being documented, including the standard library.

Namespaces and disambiguators

Namespaces and disambiguators are supported by this tool and will resolve correctly, but the prefixes are not stripped. To remove prefixes, use an explicit text for the link. [`Foo`](struct@Foo) will render as Foo, but [`struct@Foo`] will render as [struct@Foo].

Lints

The rustdoc-specific lints are not supported currently. There are no plans to support them at present. If this is required, please create an issue.