Add a cute dependency declaration snippet in your crate documentation.

Overview

dep_doc

Build Status Latest Version Rust Documentation

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

    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

    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

    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

    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

    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)

Owner
Sasha
CS student, Rustacean. She/her
Sasha
A CLI tool you can pipe code and then ask for changes, add documentation, etc, using the OpenAI API.

AiBro This is your own little coding bro, immersed in the world of AI, crypto, and all other types of over hyped tech trends. You can pipe it code and

Josh Bainbridge 5 Sep 5, 2023
📓 Simple cli snippet manager

nt Minimal cli snippet manager inspired by boom Usage USAGE: nt <SUBCOMMAND> OPTIONS: -h, --help Print help information -V, --versi

Vadim 1 Aug 11, 2022
Cargo command to create the README.md from your crate's documentation

Cargo rdme Cargo command to create your README from your crate’s documentation. Installation You can install cargo rdme with cargo by running cargo in

Diogo Sousa 42 Dec 24, 2022
a cute shell thingy that written in rust

a cute shell thingy that written in rust

奥田 龍馬 12 Dec 29, 2021
a cute language with a bunch emoji🐶

nylang a cute language with a bunch emoji documentation WIKI usage dependancies rust ( cargo ) install & uninstall install chmod +x scripts/install.sh

jumango pussu 13 Jul 4, 2022
Cute tiny operating system for RISC-V. ฅ•ω•ฅ

MoeOS ⁄(⁄ ⁄•⁄ω⁄•⁄ ⁄)⁄ ٩(^ᴗ^)۶欢迎参观MoeOS的仓库,MoeOS是一个小巧可爱(并不)的操作系统,目前全力支持RISC-V中。 (*≧▽≦)因为还只是一个玩具操作系统,就别要求她能做太多事情啦!现在功能还不完善,会慢慢加的! 编译 呐,你想给我找个家么? 目前MoeOS

Rui Li 30 Nov 11, 2022
⚙️ A cute .gitignore generator with support for custom templates

Gign A Gitignore Generator Table of Contents Examples Install Custom templates Help Examples # This is how you going to use it probably most of the ti

Vadim 6 Dec 7, 2022
✨ A simple and cute tool for exploring Wikipedia from the terminal ✨

Wikipe ✨ Wikipe ✨ is a tool to search Wikipedia from the command-line. Given a search query, it returns a list of matching Wikipedia articles, which c

Harvey 4 Dec 20, 2022
A cute and smart arm warmer sleeve ^_^

LuLuu! A cute and smart arm-warmer sleeve with a 1.3" full color TFT display built into the back of the hand ^_^ Hardware Runs on a RaspberryPi RP2040

Gray Olson 3 Oct 17, 2023
The joker_query is a cute query builder, with Joker can implement most complex queries with sugar syntax

joker_query The joker_query is most sugared query builder of Rust, with joker_query can implement most complex queries with sugar syntax Features − (O

DanyalMh 8 Dec 13, 2023
Checks all your documentation for spelling and grammar mistakes with hunspell and a nlprule based checker for grammar

cargo-spellcheck Check your spelling with hunspell and/or nlprule. Use Cases Run cargo spellcheck --fix or cargo spellcheck fix to fix all your docume

Bernhard Schuster 274 Nov 5, 2022
A zero-dependency crate for writing repetitive code easier and faster.

akin A zero-dependency crate for writing repetitive code easier and faster. Check Syntax for information about how to use it. Why? Example Syntax NONE

LyonSyonII 36 Dec 29, 2022
A truly zero-dependency crate providing quick, easy, reliable, and scalable access to the name "jordin"

jordin Finally! A truly zero-dependency crate providing quick, easy, reliable, and scalable access to the name "jordin". Additionally, this one-of-a-k

jordin 2 Aug 4, 2022
Add Facebook and Google authentication to your HTTP REST API in Actix-web

I created this project while learning Rust. Project shows how to handle Facebook and Google token verification in Rust using Actix-Web. Hope this help

null 37 Dec 31, 2022
A small tool to use along with i3/Sway to add CSS-powered decorations to your focused windows, for better usability.

glimmer What A tool for decorating i3 windows when they get focused, written in Rust. classic.mp4 Why When using i3-gaps I ran into the following prob

Daniel Acuña 26 Dec 17, 2022
Add nice user-facing diagnostics to your errors without being weird about it.

thisdiagnostic is a Rust library for adding rich diagnostic metadata to errors, for some really fancy and customizable error reporting!

Kat Marchán 14 Feb 2, 2022
Add CLI & form interface to your program

Add CLI & form interface to your program

null 292 Nov 4, 2022
Add toast support in your dioxus project

Add toast support in your dioxus project

YuKun Liu 8 Dec 16, 2022
Easily add metrics to your system -- and actually understand them using automatically customized Prometheus queries

Autometrics ?? ✨ Autometrics is a macro that makes it trivial to add useful metrics to any function in your codebase. Easily understand and debug your

Fiberplane 341 Feb 6, 2023
Easily add metrics to your system -- and actually understand them using automatically customized Prometheus queries

A Rust macro that makes it easy to understand the error rate, response time, and production usage of any function in your code. Jump from your IDE to

Autometrics 462 Mar 6, 2023