Add a cute dependency declaration snippet in your crate documentation.

Sasha

Last update: May 1, 2022

Related tags

PDF Files Processing dep-doc

Overview

`dep_doc`

Add a cute dependency declaration snippet in your crate documentation.

Adding to `Cargo.toml`

[dependencies]
dep_doc = "0.1.1"

Goal

When writing Rust libraries, it is quite common to add a code snippet which shows to the end-user how to add the crate to the Cargo.toml. The problem is that there's no way to ensure that the crate name and version are correct before releasing a new version.

This crate aims to automate the TOML snippet generation by providing macro-assisted solution which expand in the correct crate name and version. It does so by reading environment variables that are set by cargo itself.

Usage

To add the TOML snippet, insert the following line between two documentation lines:

//! Some doc...
#![doc = dep_doc::dep_doc!()]
//! Some other doc

If invoked in dep_doc, this will generates the following documentation:

Some doc...
[dependencies]
dep_doc = "0.1.1"
Some other doc

Customization

Some crates may document specific features, git repository, branches, commit hash, and so on. This can be addressed by passing code in the dep_doc invocation:

//! Some doc...
#![doc = dep_doc::dep_doc!(git = "https://github.com/scrabsha/dep-doc")]
//! Some other doc

If invoked in dep_doc, this will generate the following documentation:

Some doc...

[dependencies]
dep_doc = { version = "0.1.1", git = "https://github.com/scrabsha/dep-doc" }

Some other doc

My library is better suited as a development dependency

That's fine! dev_dep_doc generates the appropriate documentation. It replaces the [dependencies] section by a [dev-dependencies] one.

//! Some doc...
#![doc = dep_doc::dev_dep_doc!(features = ["proc_macro", "no_std"])]
//! Some other doc

If invoked in dep_doc, this will generate the following documentation:

Some doc...

[dev-dependencies]
dep_doc = { version = "0.1.1", features = ["prod_macro", "no_std"] }

Some other doc

License

^{Licensed under either of Apache License, Version 2.0 or MIT license at your option.}
_{Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this crate by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.}

Comments

Make the expansion easier to test
In previous implementation, there was a dep_doc (resp. dev_dep_doc macro, which expanded to the concatenation of the following:

the beginning of a code snippet with the section [dependencies] (resp. [dev-dependencies]),

a call to package_import with the correct package name and version passed as argument,

the ned of the code snippet.

The problem with this approach is that it was not possible to test the complete expansion of a macro, given a crate name, a version and some other information. This even resulted to a bug where we forgot to pass the so called "other information" to the package_import. See #10 for more.

This commit allows for simple testing by adding an additional intermediate step. The dep_doc (resp. dev_dep_doc) macro now expands to a call to dep_doc_inner (resp. dev_dep_doc_inner), with the crate name and version guessed from the environment and the "other information". dep_doc_inner (resp. dev_dep_doc) is then responsible for generating the concatenation described previously.

As such, most of the expansion process can be tested by calling dep_doc_inner (resp. dev_dep_doc_inner).

A bunch of tests have been added in the process in order to ensure that the previously linked bug won't happen again.
opened by scrabsha 0
Add Apache/MIT license files

These two licenses are stored in the LICENSE-APACHE and LICENSE-MIT files.

A paragraph providing information about the license has been added to the README file.

opened by scrabsha 0
Add README file
This file was generated by following these steps:

copy all the crate-level documentation,

remove the initial //!,

remove trailing whitespaces,

mentally expand every invocation of dep_doc-provided macros,

mark section (#) as subsections (##)

add a header.
opened by scrabsha 0
Always adding version is not always good

According to the Cargo Book, it is possible to declare a dependency as a git repository URI and no version whatsoever. We must handle this situation.

It would be a good idea to triple-check that we respect all the rules described in this page.

opened by scrabsha 0
Allow package renaming

Some crates such as @yozhgoor's CreateProcessW don't follow Rust's standard casing. As such, they are commonly renamed when added in the Cargo.toml file.

We could provide custom renaming via a custom syntax.

opened by scrabsha 0

Releases(v0.1.1)

v0.1.1(Nov 22, 2021)
This release fixes a bug in which additional crate information such as git repository link, branch name and feature are not passed during the expansion.

Detailed changelog:

Pass extra arguments onwards (#10),

Make the expansion easier to test (#11),

Add badges in the readme (#12).

Source code(tar.gz)
Source code(zip)
v0.1.0(Nov 22, 2021)

This is the first release! It adds the dep_doc and dev_dep_doc declarative macros. The documentation is available on docs.rs.
Source code(tar.gz)
Source code(zip)