How to document this project?

[windelbouwman]

This is gonna be some sort of a poll. So the question is, how to write proper documentation for this project. Both rust and python have documentation options. For rust, there appears to be some rust format tool, which is the default. For python there is readthedocs and sphinx.

I now see the following options:

• Document the project in readthedocs with sphinx
• Document the project in rust
• Do both options and mix

Proposals are welcome, we can vote them with the like options!

[OddBloke]

I think we'll have a couple of different audiences for documentation: RustPython end-users (i.e. Python developers) and people interested in RustPython internals (i.e. Rust developers). The former are more likely to be comfortable with Sphinx, and the latter with rustdoc.

Given the current state of development, I would lean towards using rustdoc. We can consider if we want to produce more Python-developer-friendly once we're in a state where it's actually feasible to use RustPython without knowing about the internals/the current state of development.

[cthulahoops]

That sounds reasonable to me. I don't have much experience with either tool.

[rmliddle]

I agree with @OddBloke that rustdoc is probably favourable here but my preference would be doing this in the docs directory of this repository, that way documentation can be maintained along with code.

[Ryex]

I'm looking to take on some documentation tasks to better familiarize myself with the internals. and it would be nice to get a clear answer on this question.

It appears the current state of the documentation is split between inline comments and some markdown files in the docs/ directory which also contains some presentation slides.

while it might be cleaner to document the project separately from the code rustdoc does not yet support this. we could of course not use rustdoc but it seems a waste to have to spend the documentation effort and have to do all the relevant internal linking manually when rustdoc can do it for us.

There is an unstable #![feature(external_doc)] to include external documentation tracked by rust-lang/rust#44732 .
this would let us use #[doc(include = "external-doc.md")] if some inline documentation gets too long and breaks the flow of reading the source too much.
Or #[doc(include = "../doc/external-doc.md")] would allow a doc folder to live next to the src folder of each crate.

If moving forward with inline documentation is ok what sections do people feel could benefit most from some friendly documentation? personally I feel that the macros in use would be a good place to start as that would greatly aid in helping understand the project code better.