Есть ли способ включить функцию Cargo только тогда, когда rustdoc проверяет примеры?

Question

У меня есть следующий кусок в документации к ящику:

//! # Examples
//! ```rust,no_run
//! extern crate stm32f103xx;
//! // ...
//! ```

Проблема в том, что зависимость от stm32f103xx ящик не является обязательным. Все работает нормально, если я включаю функцию stm32f103xx по умолчанию, но я не хочу делать это по умолчанию. Есть ли способ включить эту функцию только тогда, когда rustdoc проверяет примеры?

Answer 1

Нет Функции выбираются конечным пользователем ящика, и вы не единственный, кто решает запустить тесты. Если бы вы могли делать то, что вы просите, вы бы фактически заставили любого, кто хотел запустить тесты, загрузить и скомпилировать "необязательную" зависимость, что сделало бы ее не очень необязательной.

---

Вместо этого вы можете включить эту часть документации, только когда эта функция включена. Это не очевидно, но комментарии документации преобразуются в синтаксис атрибута (#[doc = "..."]). В сочетании с cfg_attrВы можете условно включить документацию, условно скомпилировать и запустить пример:

#![cfg_attr(feature = "alpha", doc = "
# Examples
```rust
fn alpha() {}
```
")]

Точно так же вы можете иметь противоположный случай для небольшой документации, которая говорит: "Проверьте эту удивительную функцию!".

Смотрите также:

• Как можно добиться условной компиляции с проектами Rust, в которых есть doctests?
• Генерация документации в макросах

Answer 2

Чтобы всегда иметь зависимость при компиляции каких-либо частей проекта (включая такие тесты), хорошо подходят Зависимости разработки.

[dev-dependencies]
stm32f103xx = "0.7.5"

Поскольку вы упоминаете, что корзина также является необязательной в качестве основной зависимости, вы можете сохранить ее в своем манифесте.

[dependencies]
stm32f103xx = { version = "0.7.5", optional = true }