From 62e3194d5f203fc04b0bf89c8ca8e35802db51f3 Mon Sep 17 00:00:00 2001 From: Muhammad Hamza Date: Sat, 15 Jan 2022 23:57:35 +0500 Subject: [PATCH] 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 | 11 +++++++++-- .github/workflows/publish-api-docs.yml | 4 ++-- api-docs/.gitignore | 1 + api-docs/before-content.html | 4 ++++ api-docs/styles.css | 15 +++++++++++++++ firebase.json | 16 +++++++++++++--- packages/yew-router/src/lib.rs | 5 +++-- packages/yew-router/src/routable.rs | 2 +- packages/yew/src/html/component/scope.rs | 4 ++-- 9 files changed, 50 insertions(+), 12 deletions(-) create mode 100644 api-docs/.gitignore create mode 100644 api-docs/before-content.html create mode 100644 api-docs/styles.css diff --git a/.github/workflows/build-api-docs.yml b/.github/workflows/build-api-docs.yml index fe8d0c62d..376eb1cd0 100644 --- a/.github/workflows/build-api-docs.yml +++ b/.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' diff --git a/.github/workflows/publish-api-docs.yml b/.github/workflows/publish-api-docs.yml index 696a907ff..fddf5a7cb 100644 --- a/.github/workflows/publish-api-docs.yml +++ b/.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 }}" diff --git a/api-docs/.gitignore b/api-docs/.gitignore new file mode 100644 index 000000000..1521c8b76 --- /dev/null +++ b/api-docs/.gitignore @@ -0,0 +1 @@ +dist diff --git a/api-docs/before-content.html b/api-docs/before-content.html new file mode 100644 index 000000000..acd9b0294 --- /dev/null +++ b/api-docs/before-content.html @@ -0,0 +1,4 @@ +
+

This is unreleased documentation for Yew Next version.

+

For up-to-date documentation, see the latest version on docs.rs.

+
diff --git a/api-docs/styles.css b/api-docs/styles.css new file mode 100644 index 000000000..9a6d18c08 --- /dev/null +++ b/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; +} diff --git a/firebase.json b/firebase.json index d302e0d11..4ee076b4f 100644 --- a/firebase.json +++ b/firebase.json @@ -8,9 +8,19 @@ }, { "target": "api", - "public": "target/doc/", - "cleanUrls": true, - "redirects": [] + "public": "api-docs/dist/", + "redirects": [ + { + "source": "/", + "destination": "https://docs.rs/yew", + "type": 302 + }, + { + "regex": "/(yew_((agent|router)?_?(macro)?))", + "destination": "https://docs.rs/:1", + "type": 302 + } + ] }, { "target": "examples", diff --git a/packages/yew-router/src/lib.rs b/packages/yew-router/src/lib.rs index 45821a289..891cfbee0 100644 --- a/packages/yew-router/src/lib.rs +++ b/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 -//! consult [`location.state()`](crate::history::Lcation::state) for detailed usage. +//! The [`Location`](gloo::history::Location) API has a way to access / store state associated with +//! session history. Please consult [`location.state()`](crate::history::Location::state) for +//! detailed usage. extern crate self as yew_router; diff --git a/packages/yew-router/src/routable.rs b/packages/yew-router/src/routable.rs index bd3da649a..6306117f7 100644 --- a/packages/yew-router/src/routable.rs +++ b/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 { diff --git a/packages/yew/src/html/component/scope.rs b/packages/yew/src/html/component/scope.rs index 70d0ce664..f4270a591 100644 --- a/packages/yew/src/html/component/scope.rs +++ b/packages/yew/src/html/component/scope.rs @@ -306,7 +306,7 @@ impl Scope { /// 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(&self, function: F) -> Callback where @@ -335,7 +335,7 @@ impl Scope { /// /// 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(&self, function: F) -> Callback where F: Fn(IN) -> OUT + 'static,