Limitations

These are the known limitations of the tool compared to rustdoc. If using the tool along with rustdoc, the generated output will differ from that of rustdoc due to these issues.

  1. The tool can only document the source code that is parsed by syn.

    A major limitation here is not being able to document meta items that are generated by macros, or items whose declarations are otherwise wrapped within a macro invocation. The only way to achieve this would be to rewrite parts of the Rust compiler, and that is far beyond the scope of this tool.

    Some features that cannot be documented by the tool due to this limitation:

    • Items defined using macros or item definitions that are inside a macro.

    • Derived traits, auto-trait implementations and blanket implementations.

    • Types determined through macro evaluation.

    • Array lengths, except when defined using literals.

    • Const expressions or other expressions that require evaluating Rust code at compile time.

    • Links to items imported with a glob use statement (e.g. use my_crate::*).

  2. Links are only possible to items that are within the same build. Intra-doc links are supported with minor changes to the docstrings, but only within the same build as well.

    Also, unlike docs.rs where links are globally generated, Sphinx can only generate links to items defined within the build process. External links can be added in the documentation itself using the RST or MD link syntax.

  3. Using RST as the format will certainly not work with other Rust tools and doctests will not execute.

    Use markdown for compatibility with Rust tooling and see Compatibility with rustdoc for any changes required to support the markdown syntax in use.

  4. Rustdoc CSS themes cannot be used with Sphinx.

    Sphinx does its own publication of HTML and so the CSS themes used have to be Sphinx compatible. If someone knows of a CSS theme that is compatible with both Sphinx and rustdoc, please create an issue with a link to the theme and it will be added here.

  5. The extension only supports the following attributes for Rust modules:

    #[cfg(test)]:

    Test modules are excluded from the extension. Currently, there is no way to include them.

    #[path = "..."]:

    Since v1.1.0, the extension supports custom paths for Rust modules defined using the path attribute. Prior to v1.1.0, the extension does not generate the right toctree for Sphinx for module’s with this attribute.