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.
Issues
  • Pass extra arguments onwards

    Pass extra arguments onwards

    It's documented that one can pass any further options, but these weren't passed on and thus always ignored.


    Thank you for this crate!

    opened by badboy 1
  • First iteration

    First iteration

    null

    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
  • 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 continuous integration

    Add continuous integration

    We perform check, test, fmt and clippy using the latest stable and check and test on the MSRV (rust 1.54).

    opened by scrabsha 0
  • Also run CI on push

    Also run CI on push

    null

    opened by scrabsha 0
  • Prepare manifest file for release

    Prepare manifest file for release

    null

    opened by scrabsha 0
  • Fix readme path in the manifest

    Fix readme path in the manifest

    null

    opened by scrabsha 0
  • 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 badges in the readme

    Add badges in the readme

    A screenshot is worth a thousand of words:

    A screenshot of the top of the readme file. We can see the crate name and three badges, respectively the Continuous Integration Status, the link to crates.io and the link to docs.rs

    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 cute shell thingy that written in rust

a cute shell thingy that written in rust

奥田 龍馬 12 Aug 13, 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 12 Nov 24, 2021
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 33 Nov 9, 2021
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 14 Nov 23, 2021
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 13 Nov 9, 2021
The open source design documentation tool for everybody

Heads up: reimagining artifact 3.0, check it out at artifact_py Artifact: design documentation for everybody Note: this project, and the python re-wri

Rett Berg 567 Nov 20, 2021
The public source and documentation for Xenon iOS tweak.

THE GUIDE HAS BEEN MOVED TO THE WIKI This is the public source for the Xenon iOS tweak. The full version is available for $1.99 on Chariz. Differences

aspen 6 Nov 2, 2021
Doku is a framework for building documentation with code-as-data methodology in mind.

Doku is a framework for building documentation with code-as-data methodology in mind. Say goodbye to stale, hand-written documentation - with D

ANIXE 63 Nov 14, 2021
Frame is a markdown language for creating state machines (automata) in 7 programming languages as well as generating UML documentation.

Frame Language Transpiler v0.5.1 Hi! So very glad you are interested in Frame. Frame system design markdown language for software architects and engin

Mark Truluck 20 Nov 26, 2021
Time-manager of delayed tasks. Like crontab, but synchronous asynchronous tasks are possible, and dynamic add/cancel/remove is supported.

delay-timer Time-manager of delayed tasks. Like crontab, but synchronous asynchronous tasks are possible, and dynamic add/cancel/remove is supported.

BinCheng 173 Nov 21, 2021
Add path effects to open glyphs in a UFO file

ufostroker Add path effects to open contours in a UFO file Given a glyph with open contours: You can apply a noodle effect: ufostroker -i Open.ufo -o

Simon Cozens 5 Jun 28, 2021
A minimal library for building compiled Node.js add-ons in Rust via Node-API

A minimal library for building compiled Node.js add-ons in Rust via Node-API

Node-API (N-API) for Rust 1.4k Nov 25, 2021
Hosts EDitor, it will add/update/delete host entries for you

Host EDitor A command-line tool to easily manage you hosts file. View Demo · Report Bug · Request Feature Table of Contents About The Project Built Wi

Arjen Wiersma 4 Nov 21, 2021
A web service that generates images of dependency graphs for crates hosted on crates.io

crate-deps A web service that generates images of dependency graphs for crates hosted on crates.io This project is built entirely in Rust using these

Corey Farwell 20 Nov 9, 2020
Zero dependency images (of chaos) in Rust

bifurcate-rs Zero dependency images (of chaos) in Rust To run: time cargo run --release > img.pgm To convert from PGM to PNG using Image Magick: conve

Stephen Merity 32 Nov 17, 2021
A dependency-free chess engine library built to run anywhere.

♔chess-engine♚ A dependency-free chess engine library built to run anywhere. Demo | Docs | Contact Me Written in Rust ?? ?? Why write a Chess engine?

adam mcdaniel 311 Nov 28, 2021
Neural network transition-based dependency parser (in Rust)

dpar Introduction dpar is a neural network transition-based dependency parser. The original Go version can be found in the oldgo branch. Dependencies

Daniël de Kok 42 Oct 22, 2021
Runtime dependency injection in Rust

This library provides an easy to use dependency injection container with a focus on ergonomics and configurability at the cost of runtime performance. For a more performance-oriented container, look for a compile-time dependency injection library.

TehPers 11 May 18, 2021
Render cargo dependency tree in online

Cargo Tree Online Check out rendered page Render cargo dependency tree in online. Usage trunk serve Copy and paste the content of Cargo.lock file to

Kangwook Lee (이강욱) 2 Sep 23, 2021
MiniJinja is a powerful but minimal dependency template engine for Rust

MiniJinja: a powerful template engine for Rust with minimal dependencies MiniJinja is a powerful but minimal dependency template engine for Rust which

Armin Ronacher 374 Nov 23, 2021
Diplo is a script runner and dependency manager made in rust mainly for Deno.

Diplo is a script runner and dependency manager made in rust mainly for Deno. Documentation Tricked.pro/diplo Installing - windows installer Features

Tricked 19 Nov 20, 2021
Yet Another Parser library for Rust. A lightweight, dependency free, parser combinator inspired set of utility methods to help with parsing strings and slices.

Yap: Yet another (rust) parsing library A lightweight, dependency free, parser combinator inspired set of utility methods to help with parsing input.

James Wilson 24 Nov 28, 2021
📦 Crate Protocol allows anyone to create, manage, and trade a tokenized basket of assets, which we refer to as a Crate.

?? Crate Protocol Crate Protocol allows anyone to create, manage, and trade a tokenized basket of assets, which we refer to as a Crate. A Crate is alw

Crate Protocol 18 Nov 27, 2021
Travis CI and AppVeyor template to test your Rust crate on 5 architectures and publish binary releases of it for Linux, macOS and Windows

trust Travis CI and AppVeyor template to test your Rust crate on 5 architectures and publish binary releases of it for Linux, macOS and Windows Featur

Jorge Aparicio 1.1k Nov 19, 2021
deductive verification of Rust code. (semi) automatically prove your code satisfies your specifications!

Le marteau-pilon, forges et aciéries de Saint-Chamond, Joseph-Fortuné LAYRAUD, 1889 About Creusot is a tool for deductive verification of Rust code. I

Xavier Denis 218 Nov 25, 2021
Employ your built-in wetware pattern recognition and signal processing facilities to understand your network traffic

Nethoscope Employ your built-in wetware pattern recognition and signal processing facilities to understand your network traffic. Check video on how it

Vesa Vilhonen 80 Nov 14, 2021
🐢 Atuin replaces your existing shell history with a SQLite database, and records additional context for your commands

Atuin replaces your existing shell history with a SQLite database, and records additional context for your commands. Additionally, it provides optional and fully encrypted synchronisation of your history between machines, via an Atuin server.

Ellie Huxtable 1.1k Nov 25, 2021
Save image from your clipboard 📋 as an image file directly from your command line! 🔥

Clpy ?? Save copied image from clipboard as an image file directly from your command line! Note It works only on windows as of now. I'll be adding sup

Piyush Suthar 12 Aug 6, 2021
Cross-platform GUI written in Rust using ADB to debloat non-rooted android devices. Improve your privacy, the security and battery life of your device.

Universal Android Debloater GUI DISCLAIMER: Use it at your own risk. I am not responsible for anything that could happen to your phone. This software

w1nst0n 1k Nov 21, 2021