Improve hosted API docs (#2373)

* build up redirects for API docs hosting

* build with all features and documenting config

* fix warnings

* can rustdoc please provide a way to modify the base url?

I want to host the docs at /next/:crate_name, not at /:crate_name ffs

* Don't clean URLs... what is rustdoc doing?

* now it wants to work???

* build a next index page

* unreleased docs banner

* show coverage

* remove ./ ???

* try 2?

* api-docs/ not api-docs-public/

* please

.github/workflows/build-api-docs.yml

@@ -30,15 +30,22 @@ jobs:
 
       - name: Run cargo doc
         uses: actions-rs/cargo@v1
+        env:
+          RUSTDOCFLAGS: --cfg documenting --html-before-content ./api-docs/before-content.html --extend-css ./api-docs/styles.css -Z unstable-options --enable-index-page
         with:
           command: doc
-          args: -p yew -p yew-macro -p yew-router -p yew-router-macro -p yew-agent --no-deps
+          args: -p yew -p yew-macro -p yew-router -p yew-router-macro -p yew-agent --no-deps --all-features
+
+      - name: Move files in correct directory
+        run: |
+          mkdir -p api-docs/dist/next
+          cp -r target/doc/* api-docs/dist/next
 
       - name: Upload build artifact
         uses: actions/upload-artifact@v2
         with:
           name: api-docs
-          path: target/doc/
+          path: api-docs/
           retention-days: 1
 
       - if: github.event_name == 'pull_request'

.github/workflows/publish-api-docs.yml

@@ -27,7 +27,7 @@ jobs:
           workflow: build-api-docs.yml
           run_id: ${{ github.event.workflow_run.id }}
           name: api-docs
-          path: target/doc/
+          path: api-docs/
 
       - if: github.event.workflow_run.event == 'pull_request'
         name: Download pr info
@@ -63,7 +63,7 @@ jobs:
           targets: api
           channelId: "${{ env.CHANNEL_ID }}"
           # link to the next version because that's what we care about
-          commentURLPath: "/yew"
+          commentURLPath: "/next/yew"
           # PR information
           prNumber: "${{ env.PR_NUMBER }}"
           prBranchName: "${{ env.PR_BRANCH }}"

api-docs/.gitignore

@@ -0,0 +1 @@
+dist

api-docs/before-content.html

@@ -0,0 +1,4 @@
+<div id="unreleased-version-header">
+    <p>This is unreleased documentation for Yew Next version.</p>
+    <p>For up-to-date documentation, see <a href="https://docs.rs/yew">the latest version on docs.rs</a>.</p>
+</div>

api-docs/styles.css

@@ -0,0 +1,15 @@
+#unreleased-version-header {
+    background-color: rgb(77, 56, 0);
+    z-index: 400;
+    position: fixed;
+    left: 0;
+    top: 0;
+    right: 0;
+    height: 70px;
+    padding-top: 10px;
+    text-align: center;
+}
+
+body {
+    padding-top: 70px !important;
+}

firebase.json

@@ -8,9 +8,19 @@
     },
     {
       "target": "api",
-      "public": "target/doc/",
+      "public": "api-docs/dist/",
-      "cleanUrls": true,
+      "redirects": [
-      "redirects": []
+        {
+          "source": "/",
+          "destination": "https://docs.rs/yew",
+          "type": 302
+        },
+        {
+          "regex": "/(yew_((agent|router)?_?(macro)?))",
+          "destination": "https://docs.rs/:1",
+          "type": 302
+        }
+      ]
     },
     {
       "target": "examples",

packages/yew-router/src/lib.rs

@@ -59,8 +59,9 @@
 //!
 //! # State
 //!
-//! The [`Location`] API has a way access / store state associated with session history. Please
+//! The [`Location`](gloo::history::Location) API has a way to access / store state associated with
-//! consult [`location.state()`](crate::history::Lcation::state) for detailed usage.
+//! session history. Please consult [`location.state()`](crate::history::Location::state) for
+//! detailed usage.
 
 extern crate self as yew_router;
 

packages/yew-router/src/routable.rs

@@ -32,7 +32,7 @@ pub trait Routable: Clone + PartialEq {
 
 /// A special route that accepts any route.
 ///
-/// This can be used with [`History`](crate::History) and [`Location`](crate::Location)
+/// This can be used with [`History`](gloo::history::History) and [`Location`](gloo::history::Location)
 /// when the type of [`Routable`] is unknown.
 #[derive(Debug, Clone, PartialEq)]
 pub struct AnyRoute {

packages/yew/src/html/component/scope.rs

@@ -306,7 +306,7 @@ impl<COMP: BaseComponent> Scope<COMP> {
     /// component's update method when invoked.
     ///
     /// Please be aware that currently the result of this callback
-    /// synchronously schedules a call to the [Component](Component)
+    /// synchronously schedules a call to the [Component](crate::Component)
     /// interface.
     pub fn callback<F, IN, M>(&self, function: F) -> Callback<IN>
     where
@@ -335,7 +335,7 @@ impl<COMP: BaseComponent> Scope<COMP> {
     ///
     /// Please be aware that currently the results of these callbacks
     /// will synchronously schedule calls to the
-    /// [Component](Component) interface.
+    /// [Component](crate::Component) interface.
     pub fn batch_callback<F, IN, OUT>(&self, function: F) -> Callback<IN>
     where
         F: Fn(IN) -> OUT + 'static,