Limitations

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 are:

   • Items defined using macros

   • Types determined through macro evaluation

   • Const expressions in generics

   • Array lengths, except when defined using literals

2. Links are only possible to items that are within the same build and must be defined explicitly as a cross-reference to the item.

   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, but they will not be used in the function signatures.

3. The tool doesn’t integrate well with the Rust ecosystem yet. Using RST as the documentation format will almost certainly cause issues with other Rust specific tools which expect Markdown. Although Rust and myst-parser both use the CommonMark specification, there are some differences in the syntax, which may not render properly in one or the other system. Every effort will be made to improve this, but it is unlikely to ever be 100% compatible with Rust’s flavor of CommonMark.