Split platform manuals by plaindocs · Pull Request #2388 · ferrocene/ferrocene

plaindocs · 2026-06-02T14:48:37Z

This PR splits out the following docs from safety manual, user manual and qualification docs:

QNX7
QNX8
RHIVOS

Into a single manual per target that contains the relevant content from the 3 documents. I've made the minimal changes required for those to make sense.

Still to do:

update tests so CI passes
update index.html to reference the new targets?
RHIVOS qualified targets?
update doc list

Review:

be great if someone familiar with the test outcomes could make sure that all looks ok
be great if someone could eyeball the new docs with fresh eyes and sure it all seems ok

jyn514 · 2026-06-24T14:13:44Z

remaining changes look ok to me but there's a bunch of rebase conflicts.

jyn514

@plaindocs you need to run cargo insta review --manifest-path src/bootstrap/Cargo.toml; see https://ops-handbook.ferrocene.dev/pr-rotation/upstream-pull-basic-checks.html.

can you confirm that x doc ferrocene/doc --exclude ferrocene/doc/rhivos-manual works and does what you expect?

about the index: since Sphinx allows python extensions, you should be able to add conditional logic here. i haven't looked at the code in detail but you can search for .py files in ferrocene/doc and that should give you an idea. let me know if you need more guidance or get stuck.

plaindocs · 2026-07-08T09:21:26Z

@jyn514 makes sense. Will check --exclude next.

The main doc index is https://github.com/ferrocene/ferrocene/tree/main/ferrocene/doc/index which is just html, so doesn't support sphinx conditionals.

plaindocs · 2026-07-08T10:15:35Z

@jyn514 I don't think --exclude works:

➜  ./x doc ferrocene/doc --exclude ferrocene/doc/rhivos-manual

...

Building Ferrocene documentation index (aarch64-apple-darwin)
Skipping Set({doc::ferrocene/doc/rhivos-manual}) because it is excluded
Build completed successfully in 0:01:14

ferrocene on  split-targets via  v26.0.0 via 🐍 v3.14.5 via 🦀 v1.96.1 took 1m14s
➜ ls build/aarch64-apple-darwin/doc/targets/rhivos-manual
_sources        document-id.txt objects.inv     rustc           search.html     signature
_static         index.html      overview.html   scope.html      searchindex.js  targets

My understanding is I need to use the 'source' doc in exclude?

I'm also not sure if building with --exclude would delete it if it was there (I lowkey expect not), but I tested for that.

jyn514 · 2026-07-08T15:07:25Z

@plaindocs it's being pull in recursively by DocumentList:

The main doc index is https://github.com/ferrocene/ferrocene/tree/main/ferrocene/doc/index which is just html, so doesn't support sphinx conditionals.

ok. i would suggest doing something like this:

Turn the HTML file into a .jinja file. There's docs here: https://jinja.palletsprojects.com/en/stable/templates/
Extend doc::Index::run to render Jinja, either in Rust or in a python wrapper. If you go the python route you can use ferrocene/doc/qualification-report/exts/ferrocene_test_outcomes/render_template.py as a reference.
Extend doc::Index to carry more data in the struct along with the target — i think we probably want a list of all targets it links to, since i imagine we'll want to have more conditional targets in the future.
Add a new build.exclude-targets = [] list to bootstrap, read from bootstrap.toml. Extend doc::Index::make_run to use it to determine the targets that are rendered.

jyn514

this looks ok for now. i've tested that x doc ferrocene/doc/index and x ferrocene/doc/qnx8 both work. we're planning to build the QNX8 docs separately as a one-off for 26.08, and worry about the long-term fix later.

the one thing i'm not sure about is whether test outcomes are going to render properly. i'm a little hesitant to merge this until we know, although i guess we can always just merge to main without backporting to 26.08. yeah ok, let's do that.

bors merge

rendered:

jyn514 · 2026-07-13T14:23:41Z

+    targets: [aarch64-unknown-linux-gnu]
+    - Set({doc::ferrocene/doc/qnx7-manual})
+[Doc] bootstrap::ferrocene::doc::QNX8Manual
+    targets: [aarch64-unknown-linux-gnu]
+    - Set({doc::ferrocene/doc/qnx8-manual})
+[Doc] bootstrap::ferrocene::doc::RHIVOSManual
+    targets: [aarch64-unknown-linux-gnu]
+    - Set({doc::ferrocene/doc/rhivos-manual})


noting explicitly that the new target docs are built by default, so they should automatically end up in the release tarball.

tshepang · 2026-07-13T14:40:25Z

bors cancel

squashing...

bors-ferrocene · 2026-07-13T14:40:30Z

Canceled.

We now have manuals for these separated - RHIVOS - QNX7 - QNX8 This commit was authored by Sam Wright. I only did some git wrangling to clean the history. Co-authored-by: Tshepang Mbambo <[email protected]>

Hoverbear

bors merge

bors-ferrocene · 2026-07-13T17:47:00Z

🕐 Waiting for PR status (Github check) to be set, probably by CI. Bors will automatically try to run when all required PR statuses are set.

bors-ferrocene · 2026-07-13T22:55:16Z

Build succeeded:

full
setup

2487: Backport to `release/1.97` r=tshepang a=ferrocene-automations[bot] This PR backports the following PRs to the `release/1.97` branch: * #2429 * #2433 * #2388 * #2475 Note that the automation failed to backport some PRs automatically. Check out the [backport:manual](https://github.com/ferrocene/ferrocene/pulls?q=is%3Apr+label%3Abackport%3Amanual) for a list of them. Co-authored-by: Urhengulas <[email protected]> Co-authored-by: Tshepang Mbambo <[email protected]> Co-authored-by: Felix Gilcher <[email protected]>

2470: sphinx/test-outcomes: make test target mandatory r=Urhengulas a=japaric see commit message for rationale. also check the qualification report target pages in tidy 2476: No RHIVOS in main safety man r=Urhengulas a=Hoverbear #2388 touched this so we touch it again. RHIVOS should be in the safety manual for RHIVOS, not main one. Co-authored-by: Jorge Aparicio <[email protected]> Co-authored-by: Ana Hobden <[email protected]>

2363: Annotations recurse into child items r=Urhengulas a=jyn514 This is useful when trying out new crates for a contract, and will also be useful for the upcoming work to add a `cfg(not(subset))` cargo fix lint. 2476: No RHIVOS in main safety man r=Urhengulas a=Hoverbear #2388 touched this so we touch it again. RHIVOS should be in the safety manual for RHIVOS, not main one. Co-authored-by: jyn <[email protected]> Co-authored-by: Johann Hemmann <[email protected]> Co-authored-by: Ana Hobden <[email protected]>

2476: No RHIVOS in main safety man r=Urhengulas a=Hoverbear #2388 touched this so we touch it again. RHIVOS should be in the safety manual for RHIVOS, not main one. Co-authored-by: Ana Hobden <[email protected]>

plaindocs marked this pull request as draft June 2, 2026 14:48

jyn514 requested changes Jun 17, 2026

View reviewed changes

Comment thread ferrocene/doc/qnx7-manual/exts/ferrocene_test_outcomes/outcomes.py Outdated

jyn514 added the waiting-on-author If this PR was opened by an automation, the "author" is the assignee. label Jun 17, 2026

jyn514 requested changes Jun 23, 2026

View reviewed changes

Comment thread ferrocene/doc/qnx7-manual/src/templates/tests.jinja2 Outdated

plaindocs marked this pull request as ready for review July 7, 2026 14:29

plaindocs changed the title ~~New QNX7 manual~~ Split platform manuals Jul 7, 2026

jyn514 reviewed Jul 7, 2026

View reviewed changes

Urhengulas reviewed Jul 8, 2026

View reviewed changes

Comment thread src/bootstrap/src/core/builder/mod.rs

jyn514 added the backport:1.97 label Jul 13, 2026

tshepang reviewed Jul 13, 2026

View reviewed changes

Comment thread ferrocene/doc/qnx8-manual/src/rustc/aarch64-unknown-qnx.rst

jyn514 approved these changes Jul 13, 2026

View reviewed changes

tshepang force-pushed the split-targets branch 2 times, most recently from 4533b93 to 0fae87e Compare July 13, 2026 16:23

tshepang reviewed Jul 13, 2026

View reviewed changes

Comment thread ferrocene/doc/index/index.html Outdated

tshepang force-pushed the split-targets branch from 0fae87e to 354e99c Compare July 13, 2026 16:54

split some of the platform manuals

95b7a57

We now have manuals for these separated - RHIVOS - QNX7 - QNX8 This commit was authored by Sam Wright. I only did some git wrangling to clean the history. Co-authored-by: Tshepang Mbambo <[email protected]>

tshepang force-pushed the split-targets branch from 354e99c to 95b7a57 Compare July 13, 2026 17:40

avoid repetitive sub-titles

00555f5

tshepang force-pushed the split-targets branch from 176db1c to 00555f5 Compare July 13, 2026 17:43

Hoverbear approved these changes Jul 13, 2026

View reviewed changes

bors-ferrocene Bot merged commit bbac114 into main Jul 13, 2026
4 checks passed

bors-ferrocene Bot deleted the split-targets branch July 13, 2026 22:55

github-actions Bot added the merged-in:1.98 label Jul 13, 2026

jyn514 mentioned this pull request Jul 14, 2026

Backport to release/1.97 #2462

Closed

ferrocene-automations Bot added the backport:manual PR requiring manual intervention to backport label Jul 14, 2026

Hoverbear mentioned this pull request Jul 14, 2026

No RHIVOS in main safety man #2476

Merged

ferrocene-automations Bot mentioned this pull request Jul 15, 2026

Backport to release/1.97 #2479

Closed

jyn514 added the merged-in:1.97 label Jul 15, 2026

ferrocene-automations Bot mentioned this pull request Jul 16, 2026

Backport to release/1.97 #2487

Merged

ferrocene-automations Bot mentioned this pull request Jul 17, 2026

Backport to release/1.97 #2491

Open

Uh oh!

Conversation

plaindocs commented Jun 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jyn514 commented Jun 24, 2026

Uh oh!

jyn514 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

plaindocs commented Jul 8, 2026

Uh oh!

plaindocs commented Jul 8, 2026

Uh oh!

jyn514 commented Jul 8, 2026

Uh oh!

Uh oh!

jyn514 left a comment

Choose a reason for hiding this comment

Uh oh!

jyn514 Jul 13, 2026

Choose a reason for hiding this comment

Uh oh!

tshepang commented Jul 13, 2026

Uh oh!

bors-ferrocene Bot commented Jul 13, 2026

Uh oh!

Uh oh!

Hoverbear left a comment

Choose a reason for hiding this comment

Uh oh!

bors-ferrocene Bot commented Jul 13, 2026

Uh oh!

bors-ferrocene Bot commented Jul 13, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

plaindocs commented Jun 2, 2026 •

edited

Loading