Sorry, sent the previous mail in a draft. The complete version is below.

From: Anton Komlev via TF-M tf-m@lists.trustedfirmware.org Sent: Thursday, June 9, 2022 1:23 PM To: tf-m@lists.trustedfirmware.org Cc: nd nd@arm.com Subject: [TF-M] Re: TF-M documentation integration

Hi,

Those are the options under discussion. Links to rendered docs in external repositories and use of interspinx expect each repo to have its own Sphinx project, which is a bit of trouble. Alternative, links to raw RST files are not that friendly to read.

There is 5th option: gather files from all repos under the main /docs during build time. This is also unwanted solution as it goes back to file copy practice as we did before for platforms' docs.

Cheers, Anton

From: David Hu <David.Hu@arm.commailto:David.Hu@arm.com> Sent: Thursday, June 9, 2022 11:15 AM To: Anton Komlev <Anton.Komlev@arm.commailto:Anton.Komlev@arm.com>; tf-m@lists.trustedfirmware.orgmailto:tf-m@lists.trustedfirmware.org Cc: nd <nd@arm.commailto:nd@arm.com> Subject: RE: TF-M documentation integration

Hi Anton,

I'm very interested in the final render output of those repos. Will those repos get their own HTML page, such as tf-m-extras-doc.trustedfirmware.org? Or are all of those repos' documents eventually collected under tf-m-user-guide.trustedfirmware.org?

Best regards, Hu Ziji

From: Anton Komlev via TF-M <tf-m@lists.trustedfirmware.orgmailto:tf-m@lists.trustedfirmware.org> Sent: Tuesday, June 7, 2022 5:44 PM To: tf-m@lists.trustedfirmware.orgmailto:tf-m@lists.trustedfirmware.org Cc: nd <nd@arm.commailto:nd@arm.com> Subject: [TF-M] TF-M documentation integration

Hello,

TF-M documentation reflects the documents in the main TF-M repository (https://git.trustedfirmware.org/TF-M/trusted-firmware-m.git/tree/docs) only. There are 5 other repos (tests, tools, extras, CI) with corresponded docs being good to be linked to the main. Looking for ideas / advice on the best way to do that.

The main problem is that Sphinx (the documentation tool) renders files under its configuration directory only, ignoring everything outside of it so reference to external repos is not an easy task. I see several solutions:

1. The main doc points to external files (*.rst) as an external link without rendering it. Like thishttps://git.trustedfirmware.org/TF-M/tf-m-tools.git/tree/depend-trace-tool/README.rst. <-- Simplest way. 2. Create Sphinx doc for each repository, store rendered output in a temporal storage and link the main to generated HTML files. 3. Use intersphinxhttps://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html to link across repositories. Again, need rendered docs in each repo and additional preparation. 4. Anything else?

Any thoughts or experience to share? Thanks in advance, Anton