From b91dc7d2b444502d282bf33ceba9a3c16713ef8d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?joseLu=C3=ADs?= Date: Tue, 26 Nov 2024 14:03:00 +0100 Subject: [PATCH] show docs for the build scripts (private) --- DOCS/CHANGELOG.md | 1 + build/environment.rs | 6 +++--- build/features.rs | 4 ++-- build/generate/mod.rs | 5 +++-- build/generate/tuple/mod.rs | 6 +++--- build/mod.rs | 9 ++++++--- build/utils.rs | 4 ++++ src/_doc/mod.rs | 4 ++++ 8 files changed, 26 insertions(+), 13 deletions(-) diff --git a/DOCS/CHANGELOG.md b/DOCS/CHANGELOG.md index 55c9ffb4..05979bae 100644 --- a/DOCS/CHANGELOG.md +++ b/DOCS/CHANGELOG.md @@ -92,6 +92,7 @@ The format is based on [Keep a Changelog], and this project adheres to - new convenience fn: `manifest_dir` in `build::utils`. - hide `no_inline` items re-exports. - new file `DOCS/VENDORED_rustdoc.md` +- show docs for the build scripts (private). ### Removed - remove custom no_std `Error` definition. diff --git a/build/environment.rs b/build/environment.rs index ed098870..abe79861 100644 --- a/build/environment.rs +++ b/build/environment.rs @@ -1,6 +1,6 @@ // devela build::utils // -//! build script environment variables +//! Build script environment variables. // pub(crate) fn main() -> Result<(), std::io::Error> { @@ -11,7 +11,7 @@ pub(crate) fn main() -> Result<(), std::io::Error> { #[cfg(feature = "__dbg")] { - use crate::utils::{println, println_heading, println_var}; + use super::utils::{println, println_heading, println_var}; // https://doc.rust-lang.org/cargo/reference/environment-variables.html println_heading("Environment variables:"); @@ -39,7 +39,7 @@ pub(crate) fn main() -> Result<(), std::io::Error> { // println_var("CARGO_ENCODED_RUSTFLAGS"); // for (key, value) in std::env::vars() { - // crate::utils::println(&format![">> {key}: {value}"]); + // super::utils::println(&format![">> {key}: {value}"]); // } } diff --git a/build/features.rs b/build/features.rs index 5303ad5d..5d4096f9 100644 --- a/build/features.rs +++ b/build/features.rs @@ -5,7 +5,7 @@ pub(crate) fn main() -> Result<(), std::io::Error> { #[cfg(feature = "__dbg")] - crate::utils::println_heading("Features & Flags:"); + super::utils::println_heading("Features & Flags:"); reflection::set_flags(); @@ -18,7 +18,7 @@ pub(crate) fn main() -> Result<(), std::io::Error> { #[rustfmt::skip] mod reflection { #[cfg(feature = "__dbg")] - use crate::utils::println; + use super::super::utils::println; use std::env::var; /// A type that associates a list of flags with a list of features. diff --git a/build/generate/mod.rs b/build/generate/mod.rs index f936c3d1..5167c8d9 100644 --- a/build/generate/mod.rs +++ b/build/generate/mod.rs @@ -4,11 +4,12 @@ // #[cfg(feature = "_tuple")] +#[cfg_attr(feature = "nightly_doc", doc(cfg(feature = "_tuple")))] mod tuple; -pub(super) fn main() -> Result<(), std::io::Error> { +pub(crate) fn main() -> Result<(), std::io::Error> { #[cfg(feature = "__dbg")] - crate::utils::println_heading("Code generation:"); + super::utils::println_heading("Code generation:"); #[cfg(feature = "_tuple")] tuple::generate()?; diff --git a/build/generate/tuple/mod.rs b/build/generate/tuple/mod.rs index a4935342..30234c38 100644 --- a/build/generate/tuple/mod.rs +++ b/build/generate/tuple/mod.rs @@ -9,7 +9,7 @@ //! - enums definitions //! - iterators definitions and implementations -use crate::utils::*; +use super::super::utils::*; use std::{ fs::{create_dir_all, read_to_string, File}, io::{BufWriter, Error, Write}, @@ -25,7 +25,7 @@ use std::{ }; #[rustfmt::skip] -pub(super) fn generate() -> Result<(), Error> { +pub(crate) fn generate() -> Result<(), Error> { let build_out_dir = out_dir_path().join("build/"); create_dir_all(&build_out_dir)?; let path = build_out_dir.join("tuple.rs"); @@ -874,6 +874,6 @@ pub(super) fn generate() -> Result<(), Error> { } // #[cfg(doc)] // format the source if we're building the docs - // crate::rustfmt_file(path); + // super::super::rustfmt_file(path); Ok(()) } diff --git a/build/mod.rs b/build/mod.rs index ef76aa2d..87cb6ed5 100644 --- a/build/mod.rs +++ b/build/mod.rs @@ -1,7 +1,11 @@ // devela build // -//! The build script. +//! The build scripts. // +// NOTE: use relative imports (super::*) instead of crate::*, +// so that it also works when compiling private documentation. + +#![cfg_attr(feature = "nightly_doc", feature(doc_cfg, doc_notable_trait))] mod environment; mod features; @@ -14,8 +18,7 @@ fn main() { } } -// WAIT:1.81 [error_in_core](https://github.com/rust-lang/rust/pull/125951) -fn try_main() -> Result<(), Box> { +fn try_main() -> Result<(), Box> { #[cfg(feature = "__dbg")] utils::println_start_end(true); diff --git a/build/utils.rs b/build/utils.rs index 280bb9c8..32738e8e 100644 --- a/build/utils.rs +++ b/build/utils.rs @@ -19,12 +19,14 @@ pub(crate) fn manifest_dir_path() -> PathBuf { /// Prints a message to *stdout* from the build script. #[cfg(feature = "__dbg")] +#[cfg_attr(feature = "nightly_doc", doc(cfg(feature = "__dbg")))] pub(crate) fn println(msg: &str) { println!("cargo:warning={}", msg); } /// Prints a heading message to *stdout*, underlined. #[cfg(feature = "__dbg")] +#[cfg_attr(feature = "nightly_doc", doc(cfg(feature = "__dbg")))] pub(crate) fn println_heading(msg: &str) { println(""); println(msg); @@ -33,6 +35,7 @@ pub(crate) fn println_heading(msg: &str) { /// Prints the value of an environment variable. #[cfg(feature = "__dbg")] +#[cfg_attr(feature = "nightly_doc", doc(cfg(feature = "__dbg")))] pub(crate) fn println_var(var: &str) { if let Ok(v) = env::var(var) { println(&format!["ยท {var}: {v}"]); @@ -44,6 +47,7 @@ pub(crate) fn println_var(var: &str) { /// Prints the build script `start` or end message to *stdout*. #[cfg(feature = "__dbg")] +#[cfg_attr(feature = "nightly_doc", doc(cfg(feature = "__dbg")))] pub(crate) fn println_start_end(start: bool) { let msg = if start { "~ Start of build script ~" diff --git a/src/_doc/mod.rs b/src/_doc/mod.rs index 1e3349b5..bed25af1 100644 --- a/src/_doc/mod.rs +++ b/src/_doc/mod.rs @@ -6,6 +6,10 @@ #![cfg(any(doc, test))] #![cfg_attr(feature = "nightly_doc", doc(cfg(doc)))] +#[cfg(feature = "std")] +#[path = "../../build/mod.rs"] +mod build; + /// Documented examples. pub mod examples;