fix log and math docu

This commit is contained in:
Christoph J. Scherr 2023-09-20 20:14:10 +02:00
parent 341a64a0f5
commit cbd0717cc6
5 changed files with 21 additions and 47 deletions

View File

@ -61,9 +61,6 @@ hedu = ["bintols"]
[lib] [lib]
name = "libpt" name = "libpt"
# I chose a bad name for my package and i will have to live with it.
# make issue here to make it possible to name the lib file in cargo
# https://github.com/rust-lang/cargo/issues/1970
crate-type = [ crate-type = [
"dylib", # .dll, .so, .dynlib "dylib", # .dll, .so, .dynlib
"staticlib" # .lib, .a "staticlib" # .lib, .a

View File

@ -16,7 +16,6 @@ categories.workspace = true
tracing = "0.1.37" tracing = "0.1.37"
tracing-appender = "0.2.2" tracing-appender = "0.2.2"
tracing-subscriber = "0.3.17" tracing-subscriber = "0.3.17"
env_logger = "0.10.0"
pyo3 = {workspace = true} pyo3 = {workspace = true}
[dev-dependencies] [dev-dependencies]

View File

@ -1,12 +1,6 @@
//! # very short description //! # Error module for [`pt-log`](crate)
//! //!
//! Short description //! This module handles errors in logging contexts.
//!
//! Details
//!
//! ## Section 1
//!
//! ## Section 2
//// ATTRIBUTES //////////////////////////////////////////////////////////////////////////////////// //// ATTRIBUTES ////////////////////////////////////////////////////////////////////////////////////
// we want docs // we want docs
@ -22,7 +16,7 @@ use pyo3::{exceptions::PyException, PyErr};
use tracing::subscriber::SetGlobalDefaultError; use tracing::subscriber::SetGlobalDefaultError;
//// TYPES ///////////////////////////////////////////////////////////////////////////////////////// //// TYPES /////////////////////////////////////////////////////////////////////////////////////////
/// a quick alias for a result with a [`LoggerError`] /// a quick alias for a result with a [`Error`]
pub type Result<T> = std::result::Result<T, Error>; pub type Result<T> = std::result::Result<T, Error>;
//// CONSTANTS ///////////////////////////////////////////////////////////////////////////////////// //// CONSTANTS /////////////////////////////////////////////////////////////////////////////////////
@ -32,7 +26,7 @@ pub type Result<T> = std::result::Result<T, Error>;
//// MACROS //////////////////////////////////////////////////////////////////////////////////////// //// MACROS ////////////////////////////////////////////////////////////////////////////////////////
//// ENUMS ///////////////////////////////////////////////////////////////////////////////////////// //// ENUMS /////////////////////////////////////////////////////////////////////////////////////////
/// ## Errors for the [logger](crate::logger) /// ## Errors for the [Logger](super::Logger)
pub enum Error { pub enum Error {
/// Bad IO operation /// Bad IO operation
IO(std::io::Error), IO(std::io::Error),

View File

@ -1,14 +1,15 @@
//! # A specialized Logger for [`pt`](crate) //! # A specialized Logger for [`pt`](../libpt/index.html)
//! //!
//! For the library version, only the basic [`log`] is used, so that it is possible for //! For the library version, only the basic [`tracing`] is used, so that it is possible for
//! the end user to use the [`log`] frontend they desire. //! the end user to use the [`tracing`] frontend they desire.
//! //!
//! I did however decide to create a [`Logger`] struct. This struct is mainly intended to be used //! I did however decide to create a [`Logger`] struct. This struct is mainly intended to be used
//! with the python module of [`pt`](crate), but is still just as usable in other contexts. //! with the python module of [`pt`](../libpt/index.html), but is still just as usable in other contexts.
//! //!
//! ## Technologies used for logging: //! ## Technologies used for logging:
//! - [`log`]: base logging crate //! - [`tracing`]: base logging crate
//! - [`env_logger`]: used for the executable //! - [`tracing_appender`]: Used to log to files
//! - [`tracing_subscriber`]: Used to do actual logging, formatting, to stdout
//// ATTRIBUTES //////////////////////////////////////////////////////////////////////////////////// //// ATTRIBUTES ////////////////////////////////////////////////////////////////////////////////////
@ -39,21 +40,10 @@ pub const DEFAULT_LOG_DIR: &'static str = "/dev/null";
static INITIALIZED: AtomicBool = AtomicBool::new(false); static INITIALIZED: AtomicBool = AtomicBool::new(false);
//// STRUCTS /////////////////////////////////////////////////////////////////////////////////////// //// STRUCTS ///////////////////////////////////////////////////////////////////////////////////////
/// ## Logger for [`pt`](crate) /// ## Logger for [`pt`](../libpt/index.html)
/// ///
/// This struct exists mainly for the python module, so that we can use the same logger with both /// This struct exists mainly for the python module, so that we can use the same logger with both
/// python and rust. /// python and rust.
///
/// ### Setting a [`Level`](log::Level)
///
/// To set a [`Level`](log::Level), you need to set the environment variable `LIBPT_LOGLEVEL`
/// to either of:
///
/// - `Trace`
/// - `Debug`
/// - `Info`
/// - `Warn`
/// - `Error`
#[pyclass] #[pyclass]
pub struct Logger {} pub struct Logger {}
@ -71,7 +61,7 @@ impl Logger {
/// ///
/// Will enable the logger to be used. /// Will enable the logger to be used.
/// ///
/// Assumes some defaults, use [`init_customized`](init_customized) for more control /// Assumes some defaults, use [`init_customized`](Self::init_customized) for more control
pub fn init(log_dir: Option<PathBuf>, max_level: Option<Level>) -> Result<()> { pub fn init(log_dir: Option<PathBuf>, max_level: Option<Level>) -> Result<()> {
Self::init_customized( Self::init_customized(
log_dir.is_some(), log_dir.is_some(),
@ -154,35 +144,35 @@ impl Logger {
} }
} }
/// ## logging at [`Level::Error`] /// ## logging at [`Level::ERROR`]
pub fn error<T>(&self, printable: T) pub fn error<T>(&self, printable: T)
where where
T: fmt::Display, T: fmt::Display,
{ {
error!("{}", printable) error!("{}", printable)
} }
/// ## logging at [`Level::Warn`] /// ## logging at [`Level::WARN`]
pub fn warn<T>(&self, printable: T) pub fn warn<T>(&self, printable: T)
where where
T: fmt::Display, T: fmt::Display,
{ {
warn!("{}", printable) warn!("{}", printable)
} }
/// ## logging at [`Level::Info`] /// ## logging at [`Level::INFO`]
pub fn info<T>(&self, printable: T) pub fn info<T>(&self, printable: T)
where where
T: fmt::Display, T: fmt::Display,
{ {
info!("{}", printable) info!("{}", printable)
} }
/// ## logging at [`Level::Debug`] /// ## logging at [`Level::DEBUG`]
pub fn debug<T>(&self, printable: T) pub fn debug<T>(&self, printable: T)
where where
T: fmt::Display, T: fmt::Display,
{ {
debug!("{}", printable) debug!("{}", printable)
} }
/// ## logging at [`Level::Trace`] /// ## logging at [`Level::TRACE`]
pub fn trace<T>(&self, printable: T) pub fn trace<T>(&self, printable: T)
where where
T: fmt::Display, T: fmt::Display,
@ -248,7 +238,7 @@ impl Logger {
//////////////////////////////////////////////////////////////////////////////////////////////////// ////////////////////////////////////////////////////////////////////////////////////////////////////
impl fmt::Debug for Logger { impl fmt::Debug for Logger {
/// ## Debug representation for [`Logger`] /// ## DEBUG representation for [`Logger`]
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
write!( write!(
f, f,

View File

@ -1,12 +1,6 @@
//! # very short description //! # General Mathmatics functionalities
//! //!
//! Short description //! This module is currently empty, but will contain many math functionalities in a future version.
//!
//! Details
//!
//! ## Section 1
//!
//! ## Section 2
//// ATTRIBUTES //////////////////////////////////////////////////////////////////////////////////// //// ATTRIBUTES ////////////////////////////////////////////////////////////////////////////////////
// we want docs // we want docs