Hi,
Those are the options are under discussion. The rendering of each repo separately required Links to rendered docs in external repositories and use of interspinx expect each repo to have an own Sphinx project, which is a bit of trouble. Alternative, links to raw RST files are not that friendly. 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 for platforms' docs before.
Cheers, Anton
From: David Hu David.Hu@arm.com Sent: Thursday, June 9, 2022 11:15 AM To: Anton Komlev Anton.Komlev@arm.com; tf-m@lists.trustedfirmware.org Cc: nd 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