More introductory documentation (#520)

* Add a comment to .rustfmt.toml explaning why it's here.

* Use `<details>` for specialized information in README.md.

* Describe a more elaborate issue-labelling system.

cranelift/.rustfmt.toml

@@ -0,0 +1 @@
+# This file tells tools we use rustfmt. We use the default settings.

cranelift/CONTRIBUTING.md

@@ -27,12 +27,24 @@ We're happy to mentor people, whether you're learning Rust, learning about
 compiler backends, learning about machine code, learning about how Cranelift
 does things, or all together at once.
 
-We tag issues in the issue tracker marked [good first issue] when we can, so
+We categorize issues in the issue tracker using a tag scheme inspired by
-that's sometimes a good place to get started. Also, we encourage people to just
+[Rust's issue tags]. For example, the [E-easy] marks good beginner issues,
-look around and find things they're interested in. This a good time to get
+and [E-rust] marks issues which likely require some familiarity with Rust,
-involved, as there aren't a lot of things set in stone yet.
+though not necessarily Cranelift-specific or even compiler-specific
+experience. [E-compiler-easy] marks issues good for beginners who have
+some familiarity with compilers, or are interested in gaining some :-).
 
-[good first issue]: https://github.com/CraneStation/cranelift/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22
+See also the [full list of labels].
+
+Also, we encourage people to just look around and find things they're
+interested in. This a good time to get involved, as there aren't a lot of
+things set in stone yet.
+
+[Rust's issue tags]: https://github.com/rust-lang/rust/blob/master/CONTRIBUTING.md#issue-triage
+[E-easy]: https://github.com/CraneStation/cranelift/labels/E-easy
+[E-rust]: https://github.com/CraneStation/cranelift/labels/E-rust
+[E-compiler-easy]: https://github.com/CraneStation/cranelift/labels/E-compiler-easy
+[full list of labels]: https://github.com/CraneStation/cranelift/labels
 
 ### Code of Conduct
 

cranelift/README.md

@@ -29,9 +29,8 @@ platforms and the Windows x64 calling convention. The performance
 of code produced by Cranelift is not yet impressive, though we have plans
 to fix that.
 
-The core codegen crates have minimal dependencies, support
+The core codegen crates have minimal dependencies, support no\_std mode
-[no\_std](#building-with-no-std) mode, and do not require any host
+(see below), and do not require any host floating-point support.
-floating-point support.
 
 Cranelift does not yet perform mitigations for Spectre or related
 security issues, though it may do so in the future. It does not
@@ -74,10 +73,10 @@ to tell cargo to visit all of the crates.
 `test-all.sh` at the top level is a script which runs all the cargo
 tests and also performs code format, lint, and documentation checks.
 
-Building with no\_std
+<details>
----------------------
+<summary>Building with no_std</summary>
 
-The following crates support \`no\_std\`:
+The following crates support \`no\_std\`, although they do depend on liballoc:
  - cranelift-entity
  - cranelift-bforest
  - cranelift-codegen
@@ -123,13 +122,19 @@ called hashmap\_core is pulled in (via the core feature). This is mostly
 the same as std::collections::HashMap, except that it doesn't have DOS
 protection. Just something to think about.
 
-Building the documentation
+</details>
---------------------------
 
-To build the Cranelift documentation, you need the [Sphinx documentation
+<details>
+<summary>Building the documentation</summary>
+
+Cranelift's documentation is [published online](https://cranelift.readthedocs.io/).
+
+To build the documentation locally, you need the [Sphinx documentation
 generator](http://www.sphinx-doc.org/) as well as Python 3::
 
     $ pip install sphinx sphinx-autobuild sphinx_rtd_theme
     $ cd cranelift/docs
     $ make html
     $ open _build/html/index.html
+
+</details>