As a pythonista who us Rust-curious, I wonder if there is any discussion of supporting docs in the compiler, the way Python has docutils ?
a question last year about the python-rust api docs is the closest I could find.
(btw @mejrs , Sphinx is a bear to set up, unless you do it frequently. I'm happy to help)
Can you elaborate a bit about what you want and why rustdoc (cargo doc) is not enough?
Yes, of course, I'll address each topic separately.
Caveat: If you don't have experience writing tech docs, then this may not make sense to you.
Enable rustdoc to support semantic markup so that writers can abstract the structure of the doc. The way that Python supports this is by having nodes on the compiler's AST corresponding to objects that can be included in docs.
AFAIK, rustdoc parses the source code for comments and then renders the content of the comment into HTML. rustdoc does not
For example, compare the source and output.
The content of this doc source, is written once: HTML
and it will produce this output, specific to each version, using the compiler as the source of truth: HTML
Depending on what you're doing, you might be able to make syn work- after all, doc comments are just fancy attributes, and syn works just fine outside of proc macros.
after all, doc comments are just fancy attributes
Bingo! Yes, that's precisely the problem, as I suspected.
Syn looks interesting and it might be a vehicle for "late binding" the values of doc elements. To encourage consistency, it's best if it's part of the standard library.
No worries, just consider me a visitor from the future, stopping by with some hints that will make more sense later.
There is support for outputting JSON on nightly.
This topic was automatically closed 90 days after the last reply. We invite you to open a new topic if you have further questions or comments.