Merge pull request #136 from mondeja/fix-docs-bare-urls

Make rustdoc links work with the book

docs/book/post_build.py

@@ -14,6 +14,7 @@ def main():
             for file in os.listdir(category_dir):
                 if file.endswith(".md") and (len(sys.argv) == 1 or (sys.argv[1] in file)):
                     build_and_copy_demo(category, file)
+                    rewrite_links(category, file)
 
 
 def build_and_copy_demo(category, md_name):
@@ -24,7 +25,8 @@ def build_and_copy_demo(category, md_name):
         code = p.wait()
 
         if code != 0:
-            sys.exit(code, f"failed to build example '{name}'")
+            sys.stderr.write(f"failed to build example '{name}'\n")
+            sys.exit(code)
 
         example_output_path = os.path.join(example_dir, "dist")
         target_path = os.path.join("book", category, name, "demo")
@@ -61,5 +63,27 @@ def build_and_copy_demo(category, md_name):
 {body_split[1]}""")
 
 
+def rewrite_links(category, md_name):
+    """Rewrite links in generated documentation to make them
+    compatible between rustdoc and the book.
+    """
+    html_name = f"{md_name[:-3]}.html"
+    target_path = os.path.join("book", category, html_name)
+
+    with open(target_path, "r") as f:
+        html = f.read()
+
+    html = html.replace(
+        "fn@crate::", "",
+    ).replace(
+        "crate::", "",
+    ).replace(
+        "fn@", "",
+    )
+
+    with open(target_path, "w") as f:
+        f.write(html)
+
+
 if __name__ == '__main__':
     main()

src/core/element_maybe_signal.rs

@@ -6,12 +6,14 @@ use std::marker::PhantomData;
 use std::ops::Deref;
 
 /// Used as an argument type to make it easily possible to pass either
+///
 /// * a `web_sys` element that implements `E` (for example `EventTarget`, `Element` or `HtmlElement`),
 /// * an `Option<T>` where `T` is the web_sys element,
 /// * a `Signal<T>` where `T` is the web_sys element,
 /// * a `Signal<Option<T>>` where `T` is the web_sys element,
 /// * a `NodeRef`
-/// into a function. Used for example in [`use_event_listener`].
+///
+/// into a function. Used for example in [`fn@crate::use_event_listener`].
 pub enum ElementMaybeSignal<T, E>
 where
     T: Into<E> + Clone + 'static,

src/core/elements_maybe_signal.rs

@@ -7,12 +7,14 @@ use std::marker::PhantomData;
 use std::ops::Deref;
 
 /// Used as an argument type to make it easily possible to pass either
+///
 /// * a `web_sys` element that implements `E` (for example `EventTarget` or `Element`),
 /// * an `Option<T>` where `T` is the web_sys element,
 /// * a `Signal<T>` where `T` is the web_sys element,
 /// * a `Signal<Option<T>>` where `T` is the web_sys element,
 /// * a `NodeRef`
-/// into a function. Used for example in [`use_event_listener`].
+///
+/// into a function. Used for example in [`fn@crate::use_event_listener`].
 pub enum ElementsMaybeSignal<T, E>
 where
     T: Into<E> + Clone + 'static,

src/lib.rs

@@ -25,7 +25,6 @@ mod is_none;
 mod is_ok;
 mod is_some;
 mod on_click_outside;
-mod use_user_media;
 mod signal_debounced;
 mod signal_throttled;
 mod sync_signal;
@@ -75,6 +74,7 @@ mod use_throttle_fn;
 mod use_timeout_fn;
 mod use_timestamp;
 mod use_to_string;
+mod use_user_media;
 mod use_web_notification;
 mod use_websocket;
 mod use_window;
@@ -91,7 +91,6 @@ pub use is_none::*;
 pub use is_ok::*;
 pub use is_some::*;
 pub use on_click_outside::*;
-pub use use_user_media::*;
 pub use signal_debounced::*;
 pub use signal_throttled::*;
 pub use sync_signal::*;
@@ -141,6 +140,7 @@ pub use use_throttle_fn::*;
 pub use use_timeout_fn::*;
 pub use use_timestamp::*;
 pub use use_to_string::*;
+pub use use_user_media::*;
 pub use use_web_notification::*;
 pub use use_websocket::*;
 pub use use_window::*;

src/on_click_outside.rs

@@ -45,9 +45,9 @@ cfg_if! { if #[cfg(not(feature = "ssr"))] {
 /// ```
 ///
 /// > This function uses [Event.composedPath()](https://developer.mozilla.org/en-US/docs/Web/API/Event/composedPath)
-/// which is **not** supported by IE 11, Edge 18 and below.
-/// If you are targeting these browsers, we recommend you to include
-/// [this code snippet](https://gist.github.com/sibbng/13e83b1dd1b733317ce0130ef07d4efd) on your project.
+/// > which is **not** supported by IE 11, Edge 18 and below.
+/// > If you are targeting these browsers, we recommend you to include
+/// > [this code snippet](https://gist.github.com/sibbng/13e83b1dd1b733317ce0130ef07d4efd) on your project.
 ///
 /// ## Excluding Elements
 ///

src/storage/use_local_storage.rs

@@ -2,14 +2,19 @@ use super::{use_storage_with_options, StorageType, UseStorageOptions};
 use codee::{Decoder, Encoder};
 use leptos::signal_prelude::*;
 
+#[allow(rustdoc::bare_urls)]
 /// Reactive [LocalStorage](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage).
 ///
-/// LocalStorage stores data in the browser with no expiration time. Access is given to all pages from the same origin (e.g., all pages from "https://example.com" share the same origin). While data doesn't expire the user can view, modify and delete all data stored. Browsers allow 5MB of data to be stored.
+/// LocalStorage stores data in the browser with no expiration time. Access is given to all pages
+/// from the same origin (e.g., all pages from "https://example.com" share the same origin).
+/// While data doesn't expire the user can view, modify and delete all data stored.
+/// Browsers allow 5MB of data to be stored.
 ///
-/// This is contrast to [`use_session_storage`] which clears data when the page session ends and is not shared.
+/// This is contrast to [`fn@crate::storage::use_session_storage`] which clears data when the page session ends and is not shared.
 ///
 /// ## Usage
-/// See [`use_storage`] for more details on how to use.
+///
+/// See [`fn@crate::storage::use_storage`] for more details on how to use.
 pub fn use_local_storage<T, C>(
     key: impl AsRef<str>,
 ) -> (Signal<T>, WriteSignal<T>, impl Fn() + Clone)

src/storage/use_session_storage.rs

@@ -6,10 +6,10 @@ use leptos::signal_prelude::*;
 ///
 /// SessionStorages stores data in the browser that is deleted when the page session ends. A page session ends when the browser closes the tab. Data is not shared between pages. While data doesn't expire the user can view, modify and delete all data stored. Browsers allow 5MB of data to be stored.
 ///
-/// Use [`use_local_storage`] to store data that is shared amongst all pages with the same origin and persists between page sessions.
+/// Use [`fn@crate::storage::use_local_storage`] to store data that is shared amongst all pages with the same origin and persists between page sessions.
 ///
 /// ## Usage
-/// See [`use_storage`] for more details on how to use.
+/// See [`fn@crate::storage::use_storage`] for more details on how to use.
 pub fn use_session_storage<T, C>(
     key: impl AsRef<str>,
 ) -> (Signal<T>, WriteSignal<T>, impl Fn() + Clone)

src/storage/use_storage.rs

@@ -23,15 +23,15 @@ const INTERNAL_STORAGE_EVENT: &str = "leptos-use-storage";
 ///
 /// Pass a [`StorageType`] to determine the kind of key-value browser storage to use.
 /// The specified key is where data is stored. All values are stored as UTF-16 strings which
-/// is then encoded and decoded via the given [`Codec`]. This value is synced with other calls using
-/// the same key on the smae page and across tabs for local storage.
+/// is then encoded and decoded via the given `*Codec`. This value is synced with other calls using
+/// the same key on the same page and across tabs for local storage.
 /// See [`UseStorageOptions`] to see how behavior can be further customised.
 ///
 /// Values are (en)decoded via the given codec. You can use any of the string codecs or a
-/// binary codec wrapped in [`Base64`].
+/// binary codec wrapped in `Base64`.
 ///
 /// > Please check [the codec chapter](https://leptos-use.rs/codecs.html) to see what codecs are
-///   available and what feature flags they require.
+/// > available and what feature flags they require.
 ///
 /// ## Example
 ///
@@ -395,7 +395,7 @@ pub enum UseStorageError<E, D> {
     ItemCodecError(CodecError<E, D>),
 }
 
-/// Options for use with [`use_local_storage_with_options`], [`use_session_storage_with_options`] and [`use_storage_with_options`].
+/// Options for use with [`fn@crate::storage::use_local_storage_with_options`], [`fn@crate::storage::use_session_storage_with_options`] and [`use_storage_with_options`].
 #[derive(DefaultBuilder)]
 pub struct UseStorageOptions<T, E, D>
 where

src/use_breakpoints.rs

@@ -37,6 +37,7 @@ use std::hash::Hash;
 /// ## Breakpoints
 ///
 /// There are many predefined breakpoints for major UI frameworks. The following are provided.
+///
 /// * [`breakpoints_tailwind`]
 /// * [`breakpoints_bootstrap_v5`]
 /// * [`breakpoints_material`]
@@ -107,7 +108,7 @@ use std::hash::Hash;
 ///
 /// ## Server-Side Rendering
 ///
-/// Since internally this uses [`use_media_query`], which returns always `false` on the server,
+/// Since internally this uses [`fn@crate::use_media_query`], which returns always `false` on the server,
 /// the returned methods also will return `false`.
 pub fn use_breakpoints<K: Eq + Hash + Debug + Clone>(
     breakpoints: HashMap<K, u32>,
@@ -276,7 +277,7 @@ impl<K: Eq + Hash + Debug + Clone> UseBreakpointsReturn<K> {
 
 /// Breakpoint keys for Tailwind V2
 ///
-/// See [https://tailwindcss.com/docs/breakpoints]
+/// See <https://tailwindcss.com/docs/breakpoints>
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
 pub enum BreakpointsTailwind {
     Sm,
@@ -288,7 +289,7 @@ pub enum BreakpointsTailwind {
 
 /// Breakpoint definitions for Tailwind V2
 ///
-/// See [https://tailwindcss.com/docs/breakpoints]
+/// See <https://tailwindcss.com/docs/breakpoints>
 pub fn breakpoints_tailwind() -> HashMap<BreakpointsTailwind, u32> {
     HashMap::from([
         (BreakpointsTailwind::Sm, 640),
@@ -301,7 +302,7 @@ pub fn breakpoints_tailwind() -> HashMap<BreakpointsTailwind, u32> {
 
 /// Breakpoint keys for Bootstrap V5
 ///
-/// See [https://getbootstrap.com/docs/5.0/layout/breakpoints]
+/// See <https://getbootstrap.com/docs/5.0/layout/breakpoints>
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
 pub enum BreakpointsBootstrapV5 {
     Sm,
@@ -313,7 +314,7 @@ pub enum BreakpointsBootstrapV5 {
 
 /// Breakpoint definitions for Bootstrap V5
 ///
-/// See [https://getbootstrap.com/docs/5.0/layout/breakpoints]
+/// <https://getbootstrap.com/docs/5.0/layout/breakpoints>
 pub fn breakpoints_bootstrap_v5() -> HashMap<BreakpointsBootstrapV5, u32> {
     HashMap::from([
         (BreakpointsBootstrapV5::Sm, 576),
@@ -326,7 +327,7 @@ pub fn breakpoints_bootstrap_v5() -> HashMap<BreakpointsBootstrapV5, u32> {
 
 /// Breakpoint keys for Material UI V5
 ///
-/// See [https://mui.com/material-ui/customization/breakpoints/]
+/// See <https://mui.com/material-ui/customization/breakpoints/>
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
 pub enum BreakpointsMaterial {
     Xs,
@@ -338,7 +339,7 @@ pub enum BreakpointsMaterial {
 
 /// Breakpoint definitions for Material UI V5
 ///
-/// See [https://mui.com/material-ui/customization/breakpoints/]
+/// See <https://mui.com/material-ui/customization/breakpoints/>
 pub fn breakpoints_material() -> HashMap<BreakpointsMaterial, u32> {
     HashMap::from([
         (BreakpointsMaterial::Xs, 1),
@@ -351,7 +352,7 @@ pub fn breakpoints_material() -> HashMap<BreakpointsMaterial, u32> {
 
 /// Breakpoint keys for Ant Design
 ///
-/// See [https://ant.design/components/layout/#breakpoint-width]
+/// See <https://ant.design/components/layout/#breakpoint-width>
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
 pub enum BreakpointsAntDesign {
     Xs,
@@ -364,7 +365,7 @@ pub enum BreakpointsAntDesign {
 
 /// Breakpoint definitions for Ant Design
 ///
-/// See [https://ant.design/components/layout/#breakpoint-width]
+/// See <https://ant.design/components/layout/#breakpoint-width>
 pub fn breakpoints_ant_design() -> HashMap<BreakpointsAntDesign, u32> {
     HashMap::from([
         (BreakpointsAntDesign::Xs, 480),
@@ -378,7 +379,7 @@ pub fn breakpoints_ant_design() -> HashMap<BreakpointsAntDesign, u32> {
 
 /// Breakpoint keys for Quasar V2
 ///
-/// See [https://quasar.dev/style/breakpoints]
+/// See <https://quasar.dev/style/breakpoints>
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
 pub enum BreakpointsQuasar {
     Xs,
@@ -390,7 +391,7 @@ pub enum BreakpointsQuasar {
 
 /// Breakpoint definitions for Quasar V2
 ///
-/// See [https://quasar.dev/style/breakpoints]
+/// See <https://quasar.dev/style/breakpoints>
 pub fn breakpoints_quasar() -> HashMap<BreakpointsQuasar, u32> {
     HashMap::from([
         (BreakpointsQuasar::Xs, 1),
@@ -401,32 +402,32 @@ pub fn breakpoints_quasar() -> HashMap<BreakpointsQuasar, u32> {
     ])
 }
 
-/// Breakpoint keys for Sematic UI
+/// Breakpoint keys for Semantic UI
 ///
-/// See [https://semantic-ui.com/elements/container.html]
+/// See <https://semantic-ui.com/elements/container.html>
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
-pub enum BreakpointsSematic {
+pub enum BreakpointsSemantic {
     Mobile,
     Tablet,
     SmallMonitor,
     LargeMonitor,
 }
 
-/// Breakpoint definitions for Sematic UI
+/// Breakpoint definitions for Semantic UI
 ///
-/// See [https://semantic-ui.com/elements/container.html]
-pub fn breakpoints_sematic() -> HashMap<BreakpointsSematic, u32> {
+/// See <https://semantic-ui.com/elements/container.html>
+pub fn breakpoints_semantic() -> HashMap<BreakpointsSemantic, u32> {
     HashMap::from([
-        (BreakpointsSematic::Mobile, 1),
-        (BreakpointsSematic::Tablet, 768),
-        (BreakpointsSematic::SmallMonitor, 992),
-        (BreakpointsSematic::LargeMonitor, 1200),
+        (BreakpointsSemantic::Mobile, 1),
+        (BreakpointsSemantic::Tablet, 768),
+        (BreakpointsSemantic::SmallMonitor, 992),
+        (BreakpointsSemantic::LargeMonitor, 1200),
     ])
 }
 
 /// Breakpoint keys for Master CSS
 ///
-/// See [https://docs.master.co/css/breakpoints]
+/// See <https://docs.master.co/css/breakpoints>
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
 pub enum BreakpointsMasterCss {
     Xxxs,
@@ -443,7 +444,7 @@ pub enum BreakpointsMasterCss {
 
 /// Breakpoint definitions for Master CSS
 ///
-/// See [https://docs.master.co/css/breakpoints]
+/// See <https://docs.master.co/css/breakpoints>
 pub fn breakpoints_master_css() -> HashMap<BreakpointsMasterCss, u32> {
     HashMap::from([
         (BreakpointsMasterCss::Xxxs, 360),

src/use_broadcast_channel.rs

@@ -45,10 +45,10 @@ use wasm_bindgen::JsValue;
 /// ```
 ///
 /// Values are (en)decoded via the given codec. You can use any of the string codecs or a
-/// binary codec wrapped in [`Base64`].
+/// binary codec wrapped in `Base64`.
 ///
 /// > Please check [the codec chapter](https://leptos-use.rs/codecs.html) to see what codecs are
-///   available and what feature flags they require.
+/// > available and what feature flags they require.
 ///
 /// ```
 /// # use leptos::*;

src/use_clipboard.rs

@@ -127,7 +127,7 @@ pub fn use_clipboard_with_options(
 pub struct UseClipboardOptions {
     /// When `true` event handlers are added so that the returned signal `text` is updated whenever the clipboard changes.
     /// Defaults to `false`.
-    /// 
+    ///
     /// > Please note that clipboard changes are only detected when copying or cutting text inside the same document.
     read: bool,