cargo new: create a README

[steveklabnik]

Was talking with @ceejbot about Rust and docs on twitter, and she had a great idea:

Also use the social engineering of cargo! Have it write a template readme for new projects!

Bundler, for example, already does this:

    $ bundle gem foolol
    $ cat foolol/README.md
    # Foolol

    Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/foolol`. To experiment with that code, run `bin/console` for an interactive prompt.

    TODO: Delete this and the text above, and describe your gem

    ## Installation

    Add this line to your application's Gemfile:

    ```ruby
    gem 'foolol'
    ```

    And then execute:

        $ bundle

    Or install it yourself as:

        $ gem install foolol

    ## Usage

    TODO: Write usage instructions here

    ## Development

    After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

    To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).

    ## Contributing

    Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/foolol.
    ```

The format that bundler is not what I would put. I think the SYNOPSIS approach pioneered by cpan and largely copied by many npm packages is the most important thing to have in a readme. Always at the top with a short code example that shows how to use the package. Starting with how to install a package is less helpful because when somebody first encounters a package, they don't know if a package appropriately solves their problem yet.

[steveklabnik]

Yeah, I'm not saying we should literally copy Bundler.

[alexcrichton]

Sounds like a great idea to me!

[carols10cents]

In the survey we ran, people also mentioned going to the documentation and wanting to see readme-like content (purpose and an example) on the front page of the docs. I think we could encourage better documentation front pages by adding a module comment to the top of the generated src/lib.rs that's something like:

//! This is the top-level module documentation in src/lib.rs.
//! This text appears on the front page of your crate's documentation;
//! preview it by running `cargo doc --open`.
//!
//! # Example
//! 
//! This is a great place to add an example of how to use your crate!
//!
//! ```
//! assert(true);
//! ```

The text talks about where it lives and where you'll see it so that if you're looking at that file, you'll know where the text ends up, and if you're looking at your generated docs, you'll know where to go to edit the text you see on the front page.

[sanmai-NL]

Creating any file as part of a project template implies that the file should be standardized in format, IMO. This is hard to do for informal/semi-structured data such as documentation. Also, the default markup language itself needs to be settled, which will lead to discussion.
Maybe a good/better first step would be toward an RFC/standard for project documentation? In that discussion Rust API documentation standards should be included as background, I think.

[steveklabnik]

This is hard to do for informal/semi-structured data such as documentation.

While this is true, there's some stuff that's common to all projects, and if it doesn't work for you, you can delete it.

Also, the default markup language itself needs to be settled, which will lead to discussion.

This is already markdown, by the vast majority.

Maybe a good/better first step would be toward an RFC/standard for project documentation?

We've had two of those! https://github.com/rust-lang/rfcs/blob/master/text/1574-more-api-documentation-conventions.md being the most recent, that built on that one.

[sanmai-NL]

Disagree on your first point. The same is true for e.g. an issue template on GitHub, ultimately rejected (rust-lang/rust#33164) because it would inconvenience those who feel it mismatches with their issue. Perhaps more people find the cargo-generated READMEs noisy (extraneous, inadequate) than helpful.

Mildly disagree with your second point. AsciiDoctor is another format that is IMO far more appropriate for software documentation than Markdown (some motivation via https://news.ycombinator.com/item?id=11292280). Discussion about this even in the Rust context is normal (https://internals.rust-lang.org/t/rustdoc-asciidoctor-vs-markdown/4161).

I am not referring to API documentation, but to user documentation. Do you agree it should be decided what content is actually ‘common to all projects’, next how to optimally present it, based on a study of evidence, before putting out README templates with cargo?

[vignesh-sankaran]

I'd be happy to take this up. I'd like to establish the scope of this particular issue.

Would this be the default behaviour with the cargo new command? And would there be a flag to disable automatic documentation creation?

My understanding of the scope so far is that there is to be a template for a README.md and a standard template for module level documentation comments. Have we agreed on a standard format regarding the format of the former?

Did we also want to warn the user on a cargo package or cargo publish if the documentation templates haven't been modified from initial creation? How about in the event that there is no documentation in the crate an author might be about to publish?

[steveklabnik]

I am not on the Cargo team, but I'd expect it to be part of the default behavior of cargo new.

I just became aware of https://github.com/RichardLitt/standard-readme, I haven't actually read it yet though.

[vignesh-sankaran]

That project looks good, I'll take a look at it. Did we want a flag to disable default documentation creation?

[sanmai-NL]

@vignesh-sankaran: Can you please address @carols10cents comment on the doc comment template? To me that is far less controversial and more productive than creating a README file in a markup format whenever Cargo is asked to initalize a new project. Can you either implement her proposal first, or can we split her proposal into a different issue?

Creating a README.md file by default implies we assume GitHub-like browsing of the new project and preference for Markdown. Probably right for most projects (but no evidence was presented here by @steveklabnik), but where do we stop with this kind of feature creep? Why not put a complete project template with various config files (e.g. Travis CI, etc.) in place? Frankly, I strongly prefer an alternative, comprehensive solution: a way for Cargo to create a new project according to a template, completely independent of README files. It is fine to me if Cargo were to have default templates for libraries and main executables that do have a README.md. But the default templates should not be arbitrarily decided. An RFC-like consensus on the template content would be far more appropriate. I foresee it will be very annoying for programmers to have to clean out newly created Cargo projects from default cruft as @steveklabnik seems to accept as a solution. Alternatively and a bit more expedient than an RFC-like consensus, would be to start separate projects for each template and to let issues be filed against it by the community to settle various details.