Rust analog to the python compiler's docutils?

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.

The goal:

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.

why not rustdoc?

AFAIK, rustdoc parses the source code for comments and then renders the content of the comment into HTML. rustdoc does not

  • publish to a different format, I have to reverse engineer the HTML.
  • represent the structure of the doc, table of contents, index, sections, footnotes.
  • expand the symbols in the code, eg. list the functions, list each functions parameters and types, etc.

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.