Documentation & Static Docs Site

[joao-conde]

Rationale

Documentation helps newcomers grasp how Parrot does what it does (best). It also helps current maintainers because we can't rely on having it all committed in memory.

A nice static website generated by cargo doc which looks like the default Rust codebase doc site would be nice to host on Github pages of this repository for instance.

Description

1. Document the main modules (for example commands) using the standard Rust doc style.

2. Create a better README splitting it into multiple markdown files stored under /docs and in the README link to them. Main sections: how to run either by installing dependencies (leave installation if possible linked to external resources so that we don't have to repeat what others did and avoid having to describe it for every OS) or using docker, how to run tests, contributing guide

3. Automatize the generation of the static site. Should amount to at the end of the main workflow (or in a new one) to do cargo doc or something similar and push it to Github pages.

4. Document discord and spotify token generation.

Reference

Documentation

• https://doc.rust-lang.org/cargo/commands/cargo-doc.html
• https://github.com/serenity-rs/serenity/blob/current/src/cache/mod.rs#L1
• https://github.com/serenity-rs/serenity/blob/current/src/cache/mod.rs#L106

Github Pages

• https://github.com/s0/git-publish-subdir-action

[afonsojramos]

As we are not a library nor a API, does it still make sense to use the default Rust Docs style of documentation? Wouldn't just better detailing some outlines in the Wiki be simpler and better adapted to our use case?

[joao-conde]

I thought about that too but I think the module documentation would help people diving into code. And since after having that all you need is to run cargo doc it seems like low-hanging fruit for me.

Also, despite being mostly a binary crate, for whatever reason I could want to use parrot as a library, perhaps to extend it (?).