-
Notifications
You must be signed in to change notification settings - Fork 10
Multiple entry points #75
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
Merged
williampMSFT
merged 47 commits into
OpenDevicePartnership:main
from
tremho:multiple-entry-points
Aug 14, 2025
Merged
Multiple entry points #75
williampMSFT
merged 47 commits into
OpenDevicePartnership:main
from
tremho:multiple-entry-points
Aug 14, 2025
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
individualized tours of documentation content by subject or role.
…tation into multiple-entry-points
…tation into multiple-entry-points
…tation into multiple-entry-points
…tation into multiple-entry-points
…tation into multiple-entry-points
individualized tours of documentation content by subject or role.
…tation into multiple-entry-points
individualized tours of documentation content by subject or role.
individualized tours of documentation content by subject or role.
…tation into multiple-entry-points
…tation into multiple-entry-points
…tation into multiple-entry-points
…tation into multiple-entry-points
…tation into multiple-entry-points
…tation into multiple-entry-points
…tation into multiple-entry-points
…tation into multiple-entry-points
williampMSFT
previously approved these changes
Aug 14, 2025
williampMSFT
approved these changes
Aug 14, 2025
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This PR introduces multiple points of entry into the overall documentation depending upon what "track" of interest a reader may have according to their subject of interest or their primary development role.
This re-introduces the concept of multiple markdown "books" being created, similar the original "bookshelf" construction, but the goal here is not to produce a virtual bookshelf of related subjects, but to offer different curated "tours" of the overall documentation, streamlining the journey for those that may not need to read the entire book.
Mdbook does not allow repeated references to the same page in the same book, so multiple books are necessary to allow these selective repeats. The publish bat and yml files handle this by copying pages from the main "guide" into the "tracks" content where needed. Additionally, a few new pages are in "tracks" to provide continuity.
Also added to the main book is a new "architecture" section that features a number of diagrams.
The book is set to flow from the beginning, and a developer-minded reader is advised to read the book from beginning to end, while other interests are advised which sections they might elect to skip over.
Existing links to this content
Because there are now multiple books, the url paths to the content has moved slightly. Page paths for the main book no longer come from the root, so any previous link to "https://opendevicepartnership.github.io/documentation/~path~" will now need to include "guide" in the path, ("https://opendevicepartnership.github.io/documentation/guide/~path~") The index page at https://opendevicepartnership.github.io/documentation/ will still work -- it is redirected to https://opendevicepartnership.github.io/documentation/guide/index.html.
The "getting started" page that I believe is currently linked to at https://opendevicepartnership.github.io/documentation/intro/welcome.html
should be changed to
https://opendevicepartnership.github.io/documentation/guide/intro/getting_started.html
to represent the new arrangement.
Note that prior to merge and publishing, a preview publish for this can be found at https://tremho.github.io/odp-documentation/
Work item tracked in this Project task