feat(docs): made perseus client-side documentable

Still need to sort out some dependency issues.

Author: arctic-hen7

.gitignore

@@ -2,7 +2,6 @@
 Cargo.lock
 pkg/
 .tribble/
-.idea/
 
 target_engine/
 target_wasm/

packages/perseus/src/error_views.rs

@@ -3,11 +3,11 @@ use crate::{errors::*, reactor::Reactor};
 use crate::{i18n::Translator, reactor::RenderMode, state::TemplateState};
 use fmterr::fmt_err;
 use serde::{Deserialize, Serialize};
-#[cfg(client)]
+#[cfg(any(client, doc))]
 use std::sync::Arc;
 #[cfg(engine)]
 use sycamore::prelude::create_scope_immediate;
-#[cfg(client)]
+#[cfg(any(client, doc))]
 use sycamore::prelude::{create_child_scope, try_use_context, ScopeDisposer};
 use sycamore::{
     prelude::{view, Scope},
@@ -49,7 +49,7 @@ pub struct ErrorViews<G: Html> {
     /// This will be extracted by the `PerseusApp` creation process and put in a
     /// place where it can be safely extracted. The replacement function
     /// will panic if called, so this should **never** be manually executed.
-    #[cfg(client)]
+    #[cfg(any(client, doc))]
     panic_handler: Arc<
         dyn Fn(Scope, ClientError, ErrorContext, ErrorPosition) -> (View<SsrNode>, View<G>)
             + Send
@@ -93,7 +93,7 @@ impl<G: Html> ErrorViews<G> {
                     _ => false,
                 }
             }),
-            #[cfg(client)]
+            #[cfg(any(client, doc))]
             panic_handler: Arc::new(handler),
         }
     }
@@ -125,7 +125,7 @@ impl<G: Html> ErrorViews<G> {
     /// Returns `true` if the given error, which must have occurred during a
     /// subsequent load, should be displayed as a popup, as opposed to
     /// occupying the entire page/widget.
-    #[cfg(client)]
+    #[cfg(any(client, doc))]
     pub(crate) fn subsequent_err_should_be_popup(&self, err: &ClientError) -> bool {
         !(self.subsequent_load_determinant)(err)
     }
@@ -171,7 +171,7 @@ impl<G: Html> ErrorViews<G> {
         })
     }
 }
-#[cfg(client)]
+#[cfg(any(client, doc))]
 impl<G: Html> ErrorViews<G> {
     /// Invokes the user's handling function, producing head/body views for the
     /// given error. From the given scope, this will determine the

packages/perseus/src/i18n/mod.rs

@@ -1,16 +1,16 @@
 // This module file is controlled, because it's used as an external module as
 // well
 
-#[cfg(client)]
+#[cfg(any(client, doc))]
 mod client_translations_manager;
-#[cfg(client)]
+#[cfg(any(client, doc))]
 mod locale_detector;
 mod locales;
 mod translations_manager;
 
-#[cfg(client)]
+#[cfg(any(client, doc))]
 pub(crate) use client_translations_manager::ClientTranslationsManager;
-#[cfg(client)]
+#[cfg(any(client, doc))]
 pub(crate) use locale_detector::detect_locale;
 pub use locales::Locales;
 pub use translations_manager::{

packages/perseus/src/init.rs

@@ -10,19 +10,19 @@ use crate::{
     stores::MutableStore,
     template::{Entity, Forever, Template},
 };
-#[cfg(client)]
+#[cfg(any(client, doc))]
 use crate::{
     error_views::{ErrorContext, ErrorPosition},
     errors::ClientError,
 };
 use crate::{errors::PluginError, template::Capsule};
 use crate::{stores::ImmutableStore, template::EntityMap};
 use futures::Future;
-#[cfg(client)]
+#[cfg(any(client, doc))]
 use std::marker::PhantomData;
 #[cfg(engine)]
 use std::pin::Pin;
-#[cfg(client)]
+#[cfg(any(client, doc))]
 use std::rc::Rc;
 use std::{any::TypeId, sync::Arc};
 use std::{collections::HashMap, panic::PanicInfo};
@@ -160,21 +160,21 @@ pub struct PerseusAppBase<G: Html, M: MutableStore, T: TranslationsManager> {
     #[cfg(engine)]
     pub(crate) static_dir: String,
     /// A handler for panics on the browser-side.
-    #[cfg(client)]
+    #[cfg(any(client, doc))]
     pub(crate) panic_handler: Option<Box<dyn Fn(&PanicInfo) + Send + Sync + 'static>>,
     /// A duplicate of the app's error handling function intended for panic
     /// handling. This must be extracted as an owned value and provided in a
     /// thread-safe manner to the panic hook system.
     ///
     /// This is in an `Arc` because panic hooks are `Fn`s, not `FnOnce`s.
-    #[cfg(client)]
+    #[cfg(any(client, doc))]
     pub(crate) panic_handler_view: Arc<
         dyn Fn(Scope, ClientError, ErrorContext, ErrorPosition) -> (View<SsrNode>, View<G>)
             + Send
             + Sync,
     >,
     // We need this on the client-side to account for the unused type parameters
-    #[cfg(client)]
+    #[cfg(any(client, doc))]
     _marker: PhantomData<(M, T)>,
 }
 impl<G: Html, M: MutableStore, T: TranslationsManager> std::fmt::Debug for PerseusAppBase<G, M, T> {
@@ -190,7 +190,7 @@ impl<G: Html, M: MutableStore, T: TranslationsManager> std::fmt::Debug for Perse
             .field("locale", &self.locales)
             .field("plugins", &self.plugins)
             .field("index_view", &self.index_view);
-        #[cfg(client)]
+        #[cfg(any(client, doc))]
         {
             return debug
                 .field(
@@ -251,7 +251,7 @@ impl<G: Html, T: TranslationsManager> PerseusAppBase<G, FsMutableStore, T> {
     /// This is asynchronous because it creates a translations manager in the
     /// background.
     // It makes no sense to implement `Default` on this, so we silence Clippy deliberately
-    #[cfg(client)]
+    #[cfg(any(client, doc))]
     #[allow(clippy::new_without_default)]
     pub fn new() -> Self {
         Self::new_wasm()
@@ -354,7 +354,7 @@ impl<G: Html, M: MutableStore, T: TranslationsManager> PerseusAppBase<G, M, T> {
             // By default, we won't use any plugins
             #[cfg(engine)]
             plugins: Arc::new(Plugins::new()),
-            #[cfg(client)]
+            #[cfg(any(client, doc))]
             plugins: Rc::new(Plugins::new()),
             #[cfg(engine)]
             immutable_store: ImmutableStore::new("./dist".to_string()),
@@ -366,17 +366,17 @@ impl<G: Html, M: MutableStore, T: TranslationsManager> PerseusAppBase<G, M, T> {
             index_view: DFLT_INDEX_VIEW.to_string(),
             #[cfg(engine)]
             static_dir: "./static".to_string(),
-            #[cfg(client)]
+            #[cfg(any(client, doc))]
             panic_handler: None,
-            #[cfg(client)]
+            #[cfg(any(client, doc))]
             panic_handler_view: ErrorViews::unlocalized_development_default().take_panic_handler(),
-            #[cfg(client)]
+            #[cfg(any(client, doc))]
             _marker: PhantomData,
         }
     }
     /// Internal function for Wasm initialization. This should never be called
     /// by the user!
-    #[cfg(client)]
+    #[cfg(any(client, doc))]
     #[doc(hidden)]
     fn new_wasm() -> Self {
         Self {
@@ -543,7 +543,7 @@ impl<G: Html, M: MutableStore, T: TranslationsManager> PerseusAppBase<G, M, T> {
     // error views.
     #[allow(unused_mut)]
     pub fn error_views(mut self, mut val: ErrorViews<G>) -> Self {
-        #[cfg(client)]
+        #[cfg(any(client, doc))]
         {
             let panic_handler = val.take_panic_handler();
             self.error_views = Some(Rc::new(val));
@@ -666,7 +666,7 @@ impl<G: Html, M: MutableStore, T: TranslationsManager> PerseusAppBase<G, M, T> {
     /// Sets the plugins that the app will use. See [`Plugins`] for
     /// further details.
     pub fn plugins(mut self, val: Plugins) -> Self {
-        #[cfg(client)]
+        #[cfg(any(client, doc))]
         {
             self.plugins = Rc::new(val);
         }
@@ -771,7 +771,7 @@ impl<G: Html, M: MutableStore, T: TranslationsManager> PerseusAppBase<G, M, T> {
     #[allow(unused_variables)]
     #[allow(unused_mut)]
     pub fn panic_handler(mut self, val: impl Fn(&PanicInfo) + Send + Sync + 'static) -> Self {
-        #[cfg(client)]
+        #[cfg(any(client, doc))]
         {
             self.panic_handler = Some(Box::new(val));
         }
@@ -908,7 +908,7 @@ impl<G: Html, M: MutableStore, T: TranslationsManager> PerseusAppBase<G, M, T> {
     //     self.entities.clone()
     // }
     // /// Gets the [`ErrorViews`] used in the app. This returns an `Rc`.
-    // #[cfg(client)]
+    // #[cfg(any(client, doc))]
     // pub fn get_error_views(&self) -> Rc<ErrorViews<G>> {
     //     self.error_views.clone()
     // }
@@ -978,7 +978,7 @@ impl<G: Html, M: MutableStore, T: TranslationsManager> PerseusAppBase<G, M, T> {
     //     self.plugins.clone()
     // }
     // /// Gets the plugins registered for the app.
-    // #[cfg(client)]
+    // #[cfg(any(client, doc))]
     // pub fn get_plugins(&self) -> Rc<Plugins> {
     //     self.plugins.clone()
     // }
@@ -1039,7 +1039,7 @@ impl<G: Html, M: MutableStore, T: TranslationsManager> PerseusAppBase<G, M, T> {
     /// # Future panics
     /// If this is called more than once, the view panic handler will panic when
     /// called.
-    #[cfg(client)]
+    #[cfg(any(client, doc))]
     pub fn take_panic_handlers(
         &mut self,
     ) -> (

packages/perseus/src/lib.rs

@@ -52,7 +52,7 @@ pub mod template;
 /// General utilities that may be useful while building Perseus apps.
 pub mod utils;
 
-#[cfg(all(feature = "client-helpers", client))]
+#[cfg(all(feature = "client-helpers", any(client, doc)))]
 mod client;
 mod init;
 mod page_data;
@@ -90,9 +90,9 @@ pub type Request = ();
 pub use perseus_macro::*;
 
 // Browser-side only
-#[cfg(client)]
+#[cfg(any(client, doc))]
 pub use crate::utils::checkpoint;
-#[cfg(all(feature = "client-helpers", client))]
+#[cfg(all(feature = "client-helpers", any(client, doc)))]
 pub use client::{run_client, ClientReturn};
 
 /// Internal utilities for lower-level work.
@@ -102,7 +102,7 @@ pub mod internal {
 }
 /// Internal utilities for logging. These are just re-exports so that users
 /// don't have to have `web_sys` and `wasm_bindgen` to use `web_log!`.
-#[cfg(client)]
+#[cfg(any(client, doc))]
 #[doc(hidden)]
 pub mod log {
     pub use wasm_bindgen::JsValue;

packages/perseus/src/reactor/global_state.rs

@@ -1,5 +1,5 @@
 use super::Reactor;
-#[cfg(client)]
+#[cfg(any(client, doc))]
 use crate::state::FrozenGlobalState;
 use crate::{
     errors::*,
@@ -96,7 +96,7 @@ impl<G: Html> Reactor<G> {
     /// Note: on the engine-side, there is no such thing as frozen state, and
     /// the active state will always be empty, so this will simply return
     /// `None`.
-    #[cfg(client)]
+    #[cfg(any(client, doc))]
     fn get_held_global_state<S>(&self) -> Result<Option<S::Rx>, ClientError>
     where
         S: MakeRx + Serialize + DeserializeOwned,
@@ -141,7 +141,7 @@ impl<G: Html> Reactor<G> {
     /// register anything in the state store. This may return an error on a
     /// downcast failure (which is probably the user's fault for providing
     /// the wrong type argument, but it's still an invariant failure).
-    #[cfg(client)]
+    #[cfg(any(client, doc))]
     fn get_active_global_state<S>(&self) -> Result<Option<S::Rx>, ClientError>
     where
         S: MakeRx + Serialize + DeserializeOwned,
@@ -155,7 +155,7 @@ impl<G: Html> Reactor<G> {
     /// the thaw preferences have already been accounted for.
     ///
     /// This assumes that the app actually supports global state.
-    #[cfg(client)]
+    #[cfg(any(client, doc))]
     fn get_frozen_global_state_and_register<S>(&self) -> Result<Option<S::Rx>, ClientError>
     where
         S: MakeRx + Serialize + DeserializeOwned,