Merge pull request #1294 from phip1611/doc7

doc: final README streamlining [doc: 6/6]

Author: phip1611

README.md

@@ -11,77 +11,37 @@ This crate makes it easy to develop Rust software that leverages **safe**,
 ![Build status](https://github.com/rust-osdev/uefi-rs/workflows/Rust/badge.svg)
 ![Stars](https://img.shields.io/github/stars/rust-osdev/uefi-rs)
 
-## Description
-
-Our mission is to provide **safe** and **performant** wrappers for UEFI
-interfaces, and allow developers to write idiomatic Rust code.
-
-This repository provides various crates:
-
-- `uefi-raw`: Raw Rust UEFI bindings for basic structures and functions.
-- `uefi`: High-level wrapper around various low-level UEFI APIs. \
-  Offers various optional features for typical Rust convenience, such as a
-  Logger and an Allocator. (_This is what you are usually looking for!_)
-- `uefi-macros`: Helper macros. Used by `uefi`.
-
-
-You can use the abstractions for example to:
-
-- create OS-specific loaders and leverage UEFI boot service
-- access UEFI runtime services from an OS
-
-[UEFI]: https://en.wikipedia.org/wiki/Unified_Extensible_Firmware_Interface
-
 ![UEFI App running in QEMU](https://imgur.com/SFPSVuO.png)
 Screenshot of an application running in QEMU on an UEFI firmware that leverages
 our Rust library.
 
-## User Documentation
-
-<!-- KEEP IN SYNC WITH uefi/README -->
-
-For a quick start, please check out [the UEFI application template](template).
+## API and User Documentation
+<!-- This section is duplicated with uefi/README.md -->
 
-The [uefi-rs book] contains a tutorial, how-tos, and overviews of some important
-UEFI concepts. Reference documentation for the various crates can be found on
-[docs.rs]:
-
-- [docs.rs/uefi](https://docs.rs/uefi)
-- [docs.rs/uefi-macros](https://docs.rs/uefi-macros)
-- [docs.rs/uefi-raw](https://docs.rs/uefi-raw)
-
-For additional information, refer to the [UEFI specification][spec].
-
-[spec]: https://uefi.org/specs/UEFI/2.10
-[uefi-rs book]: https://rust-osdev.github.io/uefi-rs/HEAD
-[docs.rs]: https://docs.rs
-
-### MSRV
-
-See the [uefi package's README](uefi/README.md#MSRV).
+The main contribution of this project is the [`uefi` crate](./uefi/README.md).
+Please refer to [docs.rs](https://docs.rs/uefi) for comprehensive documentation
+of the **latest stable release**. The latest not necessarily yet published
+documentation can be found in [`src/lib.rs`](./uefi/src/lib.rs), which can also
+be locally viewed by running `$ cargo xtask doc --open`.
 
 ## Developer Guide
 
-### Project structure
-
-This project contains multiple sub-crates:
+### Repository Structure
 
-- `uefi`: defines the standard UEFI tables / interfaces.
-  The objective is to stay unopinionated and safely wrap most interfaces.
-  Additional opinionated features (such as a Logger) are feature-gated.
-
-- `uefi-macros`: procedural macros that are used to derive some traits
-  in `uefi`.
-
-- `uefi-raw`: raw types that closely match the definitions in the UEFI
-  Specification. Safe wrappers for these types are provided by the `uefi`
-  crate. The raw types are suitable for implementing UEFI firmware.
-
-- `uefi-std-example`: Example UEFI app but as Rust standard binary.
-
-- `uefi-test-runner`: a UEFI application that runs unit / integration tests.
+This repository provides various crates:
 
-[log]: https://github.com/rust-lang-nursery/log
+- [`uefi`](/uefi/README.md): High-level wrapper around various low-level UEFI
+  APIs. This crate makes it easy to develop Rust software that leverages safe,
+  convenient, and performant abstractions for UEFI functionality.
+  This is the **main contribution** of this project.
+- [`uefi-raw`](/uefi-raw/README.md): Raw ABI-compatible types that closely
+  match the definitions in the UEFI Specification. They are suitable for
+  implementing UEFI firmware or creating interfaces to it.
+- [`uefi-macros`](/uefi-macros/README.md): Helper macros used by `uefi`.
+- [`uefi-test-runner`](/uefi-test-runner/README.md): A UEFI application that
+  runs our integration tests.
+- [`uefi-std-example`](/uefi-std-example/README.md): Example UEFI app but as
+  Rust standard binary.
 
 ### Building and testing uefi-rs
 

uefi/README.md

@@ -22,29 +22,18 @@ parse the UEFI memory map.
 _Note that for producing UEFI images, you also need to use a corresponding
 `uefi` compiler target of Rust, such as `x86_64-unknown-uefi`._
 
-For an introduction to the `uefi-rs` project and documentation, please refer to
-our main [README].
-
-[README]: https://github.com/rust-osdev/uefi-rs/blob/main/README.md
-
-## Optional features
-
-This crate's features are described in [`src/lib.rs`].
-
-[`src/lib.rs`]: src/lib.rs
-
-## MSRV
-
-The minimum supported Rust version is currently 1.70.
-
-Our policy is to support at least the past two stable releases.
-
-## License
-
-The code in this repository is licensed under the Mozilla Public License 2.
-This license allows you to use the crate in proprietary programs, but any modifications to the files must be open-sourced.
-
-The full text of the license is available in the [license file](LICENSE).
+## API and User Documentation
+<!-- This section is duplicated with /README.md -->
+
+Please refer to [docs.rs](https://docs.rs/uefi) for comprehensive documentation
+of the **latest stable release**. The latest not necessarily yet published
+documentation can be found in [`src/lib.rs`](./src/lib.rs), which can also be
+locally viewed by running `$ cargo xtask doc --open`.
+
+For an introduction to the `uefi-rs` project and this repository, please refer
+to our main [README](https://github.com/rust-osdev/uefi-rs/blob/main/README.md).
+<!-- ^ This link can't be relative as it also should work in the packaged crate
+     on crates.io. -->
 
 
 [UEFI]: https://en.wikipedia.org/wiki/Unified_Extensible_Firmware_Interface

uefi/src/lib.rs

@@ -205,17 +205,17 @@
 //! [`BootServices`]: table::boot::BootServices
 //! [`GlobalAlloc`]: alloc::alloc::GlobalAlloc
 //! [`SystemTable`]: table::SystemTable
-//! [`r-efi`]: https://crates.io/crates/r-efi
-//! [`entry-macro`]: uefi_macros::entry
 //! [`ctr16!`]: crate::cstr16
+//! [`entry-macro`]: uefi_macros::entry
+//! [`r-efi`]: https://crates.io/crates/r-efi
 //! [`unsafe_protocol`]: proto::unsafe_protocol
 //! [contributing]: https://github.com/rust-osdev/uefi-rs/blob/main/CONTRIBUTING.md
 //! [issue tracker]: https://github.com/rust-osdev/uefi-rs/issues
+//! [rustc-uefi-std]: https://doc.rust-lang.org/nightly/rustc/platform-support/unknown-uefi.html
 //! [spec]: https://uefi.org/specifications
 //! [template]: https://github.com/rust-osdev/uefi-rs/tree/main/template
-//! [unstable features]: https://doc.rust-lang.org/unstable-book/
-//! [rustc-uefi-std]: https://doc.rust-lang.org/nightly/rustc/platform-support/unknown-uefi.html
 //! [uefi-std-tr-issue]: https://github.com/rust-lang/rust/issues/100499
+//! [unstable features]: https://doc.rust-lang.org/unstable-book/
 
 #![cfg_attr(all(feature = "unstable", feature = "alloc"), feature(allocator_api))]
 #![cfg_attr(docsrs, feature(doc_auto_cfg))]