Merge pull request #136 from SpringQL/docs_include_markdown

docs: refactor lib/module document

CHANGELOG.md

@@ -4,8 +4,13 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog][Keep a Changelog] and this project adheres to [Semantic Versioning][Semantic Versioning].
 
+<!-- markdownlint-disable MD024 -->
 ## [Unreleased]
 
+### Changed
+
+- Refactor : crate/module document move to pure Markdown ([#136](https://github.com/SpringQL/SpringQL/pull/136))
+
 ## [v0.9.0]
 
 ### Added

springql-core/src/expression.md

@@ -0,0 +1,9 @@
+<!-- markdownlint-disable MD041 -->
+
+ Expression has two forms:
+
+ 1. Value expression, which is evaluated into an SqlValue from a row.
+ 2. Aggregate expression, which is evaluated into an SqlValue from set of rows.
+
+ Since SQL parser cannot distinguish column reference and value expression,
+ `ValueExprOrAlias` is used for value expressions excluding select_list.

springql-core/src/expression.rs

@@ -1,12 +1,6 @@
 // This file is part of https://github.com/SpringQL/SpringQL which is licensed under MIT OR Apache-2.0. See file LICENSE-MIT or LICENSE-APACHE for full license details.
 
-//! Expression has two forms:
-//!
-//! 1. Value expression, which is evaluated into an SqlValue from a row.
-//! 2. Aggregate expression, which is evaluated into an SqlValue from set of rows.
-//!
-//! Since SQL parser cannot distinguish column reference and value expression,
-//! `ValueExprOrAlias` is used for value expressions excluding select_list.
+#![doc = include_str!("expression.md")]
 
 pub(crate) mod boolean_expression;
 pub(crate) mod function_call;

springql-core/src/lib.md

@@ -0,0 +1,6 @@
+<!-- markdownlint-disable MD041 -->
+ SpringQL-core implementation.
+
+## High-level architecture diagram
+
+![High-level architecture diagram](https://raw.githubusercontent.com/SpringQL/SpringQL.github.io/main/static/img/springql-architecture.svg)

springql-core/src/lib.rs

@@ -1,11 +1,6 @@
 // This file is part of https://github.com/SpringQL/SpringQL which is licensed under MIT OR Apache-2.0. See file LICENSE-MIT or LICENSE-APACHE for full license details.
 
-//! SpringQL-core implementation.
-//!
-//! # High-level architecture diagram
-//!
-//! ![High-level architecture diagram](https://raw.githubusercontent.com/SpringQL/SpringQL.github.io/main/static/img/springql-architecture.svg)
-
+#![doc = include_str!("lib.md")]
 #![deny(missing_debug_implementations, missing_docs)]
 
 #[macro_use]

springql-core/src/pipeline.md

@@ -0,0 +1,12 @@
+# Pipeline concept diagram
+
+Omit _Task Graph_ here. A pipeline has:
+
+- Stream
+  - (native) Stream
+  - Source/Sink Stream
+- Source Reader
+- Sink Writer
+- Pump
+
+![Pipeline concept diagram](https://raw.githubusercontent.com/SpringQL/SpringQL.github.io/main/static/img/pipeline-and-task-graph.svg)

springql-core/src/pipeline.rs

@@ -1,17 +1,6 @@
 // This file is part of https://github.com/SpringQL/SpringQL which is licensed under MIT OR Apache-2.0. See file LICENSE-MIT or LICENSE-APACHE for full license details.
 
-//! # Pipeline concept diagram
-//!
-//! Omit _Task Graph_ here. A pipeline has:
-//!
-//!   - Stream
-//!     - (native) Stream
-//!     - Source/Sink Stream
-//!   - Source Reader
-//!   - Sink Writer
-//!   - Pump
-//!
-//! ![Pipeline concept diagram](https://raw.githubusercontent.com/SpringQL/SpringQL.github.io/main/static/img/pipeline-and-task-graph.svg)
+#![doc = include_str!("pipeline.md")]
 
 pub(crate) mod field;
 pub(crate) mod name;

springql-core/src/stream_engine.md

@@ -0,0 +1,27 @@
+<!-- markdownlint-disable MD041 -->
+
+Stream Engine component.
+
+Responsible for pipeline management and execution.
+
+Stream engine has 2 executors:
+
+1. SQL executor
+2. Autonomous executor
+
+SQL executor receives commands from user interface to quickly change some status of a pipeline.
+It does not deal with stream data (Row, to be precise).
+
+Autonomous executor deals with stream data.
+
+Both SQL executor and autonomous executor instance run at a main thread, while autonomous executor has workers which run at different worker threads.
+
+## Entities inside Stream Engine
+
+![Entities inside Stream Engine](https://raw.githubusercontent.com/SpringQL/SpringQL.github.io/main/static/img/stream-engine-architecture-entity.svg)
+
+## Communication between entities
+
+Workers in AutonomousExecutor interact via EventQueue (Choreography-based Saga pattern).
+
+![Communication between entities](https://raw.githubusercontent.com/SpringQL/SpringQL.github.io/main/static/img/stream-engine-architecture-communication.svg)

springql-core/src/stream_engine.rs

@@ -1,30 +1,6 @@
 // This file is part of https://github.com/SpringQL/SpringQL which is licensed under MIT OR Apache-2.0. See file LICENSE-MIT or LICENSE-APACHE for full license details.
 
-//! Stream Engine component.
-//!
-//! Responsible for pipeline management and execution.
-//!
-//! Stream engine has 2 executors:
-//!
-//! 1. SQL executor
-//! 2. Autonomous executor
-//!
-//! SQL executor receives commands from user interface to quickly change some status of a pipeline.
-//! It does not deal with stream data (Row, to be precise).
-//!
-//! Autonomous executor deals with stream data.
-//!
-//! Both SQL executor and autonomous executor instance run at a main thread, while autonomous executor has workers which run at different worker threads.
-//!
-//! # Entities inside Stream Engine
-//!
-//! ![Entities inside Stream Engine](https://raw.githubusercontent.com/SpringQL/SpringQL.github.io/main/static/img/stream-engine-architecture-entity.svg)
-//!
-//! # Communication between entities
-//!
-//! Workers in AutonomousExecutor interact via EventQueue (Choreography-based Saga pattern).
-//!
-//! ![Communication between entities](https://raw.githubusercontent.com/SpringQL/SpringQL.github.io/main/static/img/stream-engine-architecture-communication.svg)
+#![doc = include_str!("stream_engine.md")]
 
 pub use autonomous_executor::SpringValue;