Doc: Update link in doc to docs.rs

The outdated online documentation at https://datafuselabs.github.io is
no longer maintained due to being out-of-date and lacking version
control. In this commit, we have updated the links that previously
directed users to the old site, to now point to `docs.rs`, which
naturally supports documentation versioning.

And replace list with head for `feature-flags.md`, so that it's able to
link to a certain feature-flag.

Makefile

@@ -36,6 +36,7 @@ fix:
 
 doc:
 	make -C openraft/src/docs/faq
+	make -C openraft/src/docs/feature_flags
 	RUSTDOCFLAGS="-D warnings" cargo doc --document-private-items --all --no-deps
 
 check_missing_doc:

openraft/src/compat/compat07.rs

@@ -1,9 +1,10 @@
 //! This mod provides types that can be deserialized from data written by either v0.7 or
 //! the latest openraft.
 //!
-//! This mod is enabled by feature flag `compat-07`. See: [feature-flag-compat-07](https://datafuselabs.github.io/openraft/feature-flags)
-//! Ap application does not needs to enable this feature if it chooses to manually upgrade v0.7
-//! on-disk data.
+//! This mod is enabled by feature flag `compat-07`.
+//! See: [feature-flag-compat-07](`crate::docs::feature_flags#feature-flag-compat-07`).
+//! Ap application does not needs to enable this feature if it chooses
+//! to manually upgrade v0.7 on-disk data.
 //!
 //! In v0.7 compatible mode, openraft enables feature flags:
 //! - `serde`: it adds `serde` implementation to types such as `LogId`.
@@ -15,10 +16,15 @@
 //!
 //! An application that tries to upgrade from v0.7 can use types in this mod to replace the
 //! corresponding ones in a `RaftStorage` implementation, so that v0.7 data and v0.8 data can both
-//! be read. [rocksstore-compat07](https://github.com/datafuselabs/openraft/tree/main/rocksstore-compat07) is an example using these type to implement an upgraded RaftStorage
+//! be read.
+//! [rocksstore-compat07](https://github.com/datafuselabs/openraft/tree/main/rocksstore-compat07)
+//! is an example using these type to implement an upgraded RaftStorage
 //!
 //! This mod also provides a testing suite [`testing::Suite07`] to ensure old data will be correctly
-//! read. An application should ensure its storage to pass test suite like [rocksstore-compat07/compatibility_test.rs](https://github.com/datafuselabs/openraft/blob/main/rocksstore-compat07/src/compatibility_test.rs) does:
+//! read.
+//! An application should ensure its storage
+//! to pass test suite like [rocksstore-compat07/compatibility_test.rs](https://github.com/datafuselabs/openraft/blob/main/rocksstore-compat07/src/compatibility_test.rs)
+//! does:
 //! ```ignore
 //! use openraft::compat;
 //!

openraft/src/compat/testing.rs

@@ -1,6 +1,9 @@
 //! This mod provides supporting utilities for compatibility testing.
 //!
-//! An application that tries to be compatible with an older format data must ensure its `RaftStorage` implementation to pass test suite, just like [rocksstore-compat07/compatibility_test.rs](https://github.com/datafuselabs/openraft/blob/main/rocksstore-compat07/src/compatibility_test.rs) does
+//! An application that tries to be compatible with an older format data
+//! must ensure its `RaftStorage` implementation to pass test suite,
+//! just like [rocksstore-compat07/compatibility_test.rs](https://github.com/datafuselabs/openraft/blob/main/rocksstore-compat07/src/compatibility_test.rs)
+//! does
 
 use std::path::Path;
 

openraft/src/core/raft_core.rs

@@ -586,7 +586,9 @@ where
     /// Handle the admin command `initialize`.
     ///
     /// It is allowed to initialize only when `last_log_id.is_none()` and `vote==(0,0)`.
-    /// See: [Conditions for initialization](https://datafuselabs.github.io/openraft/cluster-formation.html#conditions-for-initialization)
+    /// See: [Conditions for initialization][precondition]
+    ///
+    /// [precondition]: crate::docs::cluster_control::cluster_formation#preconditions-for-initialization
     #[tracing::instrument(level = "debug", skip(self, tx))]
     pub(crate) fn handle_initialize(
         &mut self,

openraft/src/docs/feature_flags/Makefile

@@ -0,0 +1,6 @@
+all:
+	# dependency:
+	# https://github.com/jonschlinkert/markdown-toc#cli
+	#   brew install markdown-toc
+	markdown-toc feature-flags.md  > feature-flags-toc.md
+	echo "" >> feature-flags-toc.md

openraft/src/docs/feature_flags/feature-flags-toc.md

@@ -0,0 +1,10 @@
+- [feature-flag `bench`](#feature-flag-bench)
+- [feature-flag `bt`](#feature-flag-bt)
+- [feature-flag `compat-07`](#feature-flag-compat-07)
+- [feature-flag `generic-snapshot-data`](#feature-flag-generic-snapshot-data)
+- [feature-flag `loosen-follower-log-revert`](#feature-flag-loosen-follower-log-revert)
+- [feature-flag `serde`](#feature-flag-serde)
+- [feature-flag `single-term-leader`](#feature-flag-single-term-leader)
+- [feature-flag `singlethreaded`](#feature-flag-singlethreaded)
+- [feature-flag `storage-v2`](#feature-flag-storage-v2)
+- [feature-flag `tracing-log`](#feature-flag-tracing-log)

openraft/src/docs/feature_flags/feature-flags.md

@@ -1,89 +1,100 @@
-# Feature flags
 
 By default openraft enables no features.
 
-- `bench`: Enables benchmarks in unittest. Benchmark in openraft depends on the unstable feature
-  `test` thus it can not be used with stable rust. In order to run the benchmark with stable
-  toolchain, the unstable features have to be enabled explicitly with environment variable
-  `RUSTC_BOOTSTRAP=1`.
-  <br/><br/>
-
-- `bt`:
-  attaches backtrace to generated errors. This feature works ONLY with nightly rust, because it requires unstable feature `error_generic_member_access`.
-  <br/><br/>
-
-- `loosen-follower-log-revert`:
-  Permit the follower's log to roll back to an earlier state without causing the leader to panic.
-  Although log state reversion is typically seen as a bug, enabling it can be useful for testing or other special scenarios.
-  For instance, in an even number nodes cluster, erasing a node's data and then rebooting it(log reverts to empty) will not result in data loss.
-
-  **Do not use it unless you know what you are doing**.
-  <br/><br/>
-
-- `serde`: derives `serde::Serialize, serde::Deserialize` for type that are used
-  in storage and network, such as `Vote` or `AppendEntriesRequest`.
-  <br/><br/>
-
-- `single-term-leader`: allows only one leader to be elected in each `term`.
-  This is the standard raft policy, which increases election conflict rate
-  but reduce `LogId` size(`(term, node_id, index)` to `(term, index)`).
-
-  Read more about how it is implemented in:
-  [`leader_id`](crate::docs::data::leader_id)
-  and [`vote`](crate::docs::data::vote).
-  <br/><br/>
-
-- `compat-07`: provides additional data types to build v0.7 compatible RaftStorage.
-
-   ```toml
-   compat-07 = ["compat", "single-term-leader", "serde", "dep:or07", "compat-07-testing"]
-   compat-07-testing = ["dep:tempdir", "anyhow", "dep:serde_json"]
-   ```
-  <br/><br/>
-
-- `storage-v2`: enables `RaftLogStorage` and `RaftStateMachine` as the v2 storage
-  This is a temporary feature flag, and will be removed in the future, when v2 storage is stable.
-  This feature disables `Adapter`, which is for v1 storage to be used as v2.
-  V2 storage separates log store and state machine store so that log IO and state machine IO can be parallelized naturally.
-  <br/><br/>
-
-- `singlethreaded`: removes `Send` and `Sync` bounds from `AppData`, `AppDataResponse`, `RaftEntry`, `SnapshotData`
-  and other types to force the  asynchronous runtime to spawn any tasks in the current thread.
-  This is for any single-threaded application that never allows a raft instance to be shared among multiple threads.
-  This feature relies on the `async_fn_in_trait` language feature that is officially supported from Rust 1.75.0.
-  If the feature is enabled, affected asynchronous trait methods require `Send` bounds.
-  In order to use the feature, `AsyncRuntime::spawn` should invoke `tokio::task::spawn_local` or equivalents.
-  <br/><br/>
-
-- `generic-snapshot-data`: Enable this feature flag
-  to eliminate the `AsyncRead + AsyncWrite + AsyncSeek + Unpin` bound
-  from [`RaftTypeConfig::SnapshotData`](crate::RaftTypeConfig::SnapshotData)
-  Enabling this feature allows applications to use a custom snapshot data format and transport fragmentation,
-  diverging from the default implementation which typically relies on a single-file structure.
-
-  By default, it is off.
-  This feature is introduced in 0.9.0
-
-  On the sending end (leader that sends snapshot to follower):
-
-  - Without `generic-snapshot-data`: [`RaftNetwork::snapshot()`]
-    provides a default implementation that invokes the chunk-based API
-    [`RaftNetwork::install_snapshot()`] for transmit.
-
-  - With `generic-snapshot-data` enabled: [`RaftNetwork::snapshot()`]
-    must be implemented to provide application customized snapshot transmission.
-    Application does not need to implement [`RaftNetwork::install_snapshot()`].
-
-  On the receiving end(follower):
-
-  - `Raft::install_snapshot()` is available only when `generic-snapshot-data` is disabled.
-
-  Refer to example `examples/raft-kv-memstore-generic-snapshot-data` with `generic-snapshot-data` enabled.
-  <br/><br/>
-
-- `tracing-log`: enables "log" feature in `tracing` crate, to let tracing events
-  emit log record.
-  See: [tracing doc: emitting-log-records](https://docs.rs/tracing/latest/tracing/#emitting-log-records)
+## feature-flag `bench`
+
+Enables benchmarks in unittest. Benchmark in openraft depends on the unstable feature
+`test` thus it can not be used with stable rust. In order to run the benchmark with stable
+toolchain, the unstable features have to be enabled explicitly with environment variable
+`RUSTC_BOOTSTRAP=1`.
+
+## feature-flag `bt`
+
+attaches backtrace to generated errors.
+This feature works ONLY with nightly rust, because it requires unstable feature `error_generic_member_access`.
+
+## feature-flag `compat-07`
+
+Provides additional data types to build v0.7 compatible RaftStorage.
+
+ ```toml
+ compat-07 = ["compat", "single-term-leader", "serde", "dep:or07", "compat-07-testing"]
+ compat-07-testing = ["dep:tempdir", "anyhow", "dep:serde_json"]
+ ```
+
+## feature-flag `generic-snapshot-data`
+
+Enable this feature flag
+to eliminate the `AsyncRead + AsyncWrite + AsyncSeek + Unpin` bound
+from [`RaftTypeConfig::SnapshotData`](crate::RaftTypeConfig::SnapshotData)
+Enabling this feature allows applications to use a custom snapshot data format and transport fragmentation,
+diverging from the default implementation which typically relies on a single-file structure.
+
+By default, it is off.
+This feature is introduced in 0.9.0
+
+On the sending end (leader that sends snapshot to follower):
+
+- Without `generic-snapshot-data`: [`RaftNetwork::snapshot()`]
+  provides a default implementation that invokes the chunk-based API
+  [`RaftNetwork::install_snapshot()`] for transmit.
+
+- With `generic-snapshot-data` enabled: [`RaftNetwork::snapshot()`]
+  must be implemented to provide application customized snapshot transmission.
+  Application does not need to implement [`RaftNetwork::install_snapshot()`].
+
+On the receiving end(follower):
+
+- `Raft::install_snapshot()` is available only when `generic-snapshot-data` is disabled.
+
+Refer to example `examples/raft-kv-memstore-generic-snapshot-data` with `generic-snapshot-data` enabled.
+
+## feature-flag `loosen-follower-log-revert`
+
+Permit the follower's log to roll back to an earlier state without causing the leader to panic.
+Although log state reversion is typically seen as a bug, enabling it can be useful for testing or other special scenarios.
+For instance, in an even number nodes cluster,
+erasing a node's data and then rebooting it(log reverts to empty) will not result in data loss.
+
+**Do not use it unless you know what you are doing**.
+
+## feature-flag `serde`
+
+Derives `serde::Serialize, serde::Deserialize` for type that are used
+in storage and network, such as `Vote` or `AppendEntriesRequest`.
+
+## feature-flag `single-term-leader`
+
+Allows only one leader to be elected in each `term`.
+This is the standard raft policy, which increases election conflict rate
+but reduce `LogId` size(`(term, node_id, index)` to `(term, index)`).
+
+Read more about how it is implemented in:
+[`leader_id`](crate::docs::data::leader_id)
+and [`vote`](crate::docs::data::vote).
+
+## feature-flag `singlethreaded`
+
+Removes `Send` and `Sync` bounds from `AppData`, `AppDataResponse`, `RaftEntry`, `SnapshotData`
+and other types to force the  asynchronous runtime to spawn any tasks in the current thread.
+This is for any single-threaded application that never allows a raft instance to be shared among multiple threads.
+This feature relies on the `async_fn_in_trait` language feature that is officially supported from Rust 1.75.0.
+If the feature is enabled, affected asynchronous trait methods require `Send` bounds.
+In order to use the feature, `AsyncRuntime::spawn` should invoke `tokio::task::spawn_local` or equivalents.
+
+## feature-flag `storage-v2`
+
+Enables `RaftLogStorage` and `RaftStateMachine` as the v2 storage
+This is a temporary feature flag, and will be removed in the future, when v2 storage is stable.
+This feature disables `Adapter`, which is for v1 storage to be used as v2.
+V2 storage separates log store and state machine store so that log IO and state machine IO can be parallelized naturally.
+
+## feature-flag `tracing-log`
+
+Enables "log" feature in `tracing` crate, to let tracing events
+emit log record.
+See: [tracing doc: emitting-log-records](https://docs.rs/tracing/latest/tracing/#emitting-log-records)
+
 
 [`RaftNetwork::snapshot()`]: crate::network::RaftNetwork::snapshot
 [`RaftNetwork::install_snapshot()`]: crate::network::RaftNetwork::install_snapshot

openraft/src/docs/feature_flags/mod.rs

@@ -1 +1,5 @@
+//! # Feature flags
+
+#![doc = include_str!("feature-flags-toc.md")]
+//
 #![doc = include_str!("feature-flags.md")]