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.org>
Sent: Tuesday, June 7, 2022 5:44 PM
To: tf-m@lists.trustedfirmware.org
Cc: nd <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 this. ß 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 intersphinx 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