Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

217 fix docc tutorial deployment #266

Merged

Conversation

Jakayus
Copy link
Sponsor Contributor

@Jakayus Jakayus commented Nov 19, 2023

What it Does

How I Tested

Part 1: Create the Link for the Tutorials

  • Inside the Basic-Car-Maintenance documentation Article: add a link to the Getting started tutorial using <doc:Tutorial-Table-of-Contents> command. (Note that the hyperlink comes out as "Getting Started")
  • Go to Product -> Build Documentation
  • Verify Tutorial is linked from within the document article
  • Commit/Push changes

Part 2: Check site hosting is still working

  • Update the build script and remove the repo name reference, so that --hosting-base-path "Basic-Car-Maintenance" becomes --hosting-base-path ""
  • Run the build-docc.sh script
  • Run the following python command to host the documentation locally: /usr/bin/python3 -m http.server -d .docs
  • In new private browsing safari window, enter localhost:8000 into the URL bar
  • The documentation should now appear as it would when it is hosted from GitHub actions
  • Dismiss local changes as they were for testing only

Notes

  • Documents and Tutorials are separated when statically hosting docc archives (at least when using the docc process-archive transform-for-static-hosting command. The build script at the bottom has the command '<script>window.location.href += "documentation/basic_car_maintenance"</script>' > .docs/index.html which means start at the Documentation side of the DocC hosting.
  • Could not find a way to host it similar to how Xcode Builds it with both Documentation and Tutorials in the Side Pane, so adding a link to the tutorials files seemed like the quickest option to get tutorials hosted. WWDC 22 video "What's new in Swift DocC" appeared to show loading directly from the archive (without static hosting command) on GitHub pages, but I could not get this to work.

Screenshot

The following show the documentation loaded via "local host" in private browsing in Safari (so that browser doesn't accidentally cache previous attempts at loading the page).

test_tutorial_1
test_tutorial_2

@mikaelacaron mikaelacaron merged commit 2daf49a into mikaelacaron:dev Nov 21, 2023
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

BUG - DocC Tutorial Isn't Deployed
2 participants