Psa api 1.0.0 docs #394

Merged

gilles-peskine-arm merged 4 commits from psa-api-1.0.0-docs into master

2020-04-20 11:52:30 -05:00

gilles-peskine-arm commented

2020-04-17 10:08:21 -05:00

(Migrated from github.com)

Update PSA API specification to 1.0.0
Update Mbed Crypto references to Mbed TLS
Remove old, unlinked copy of the PSA driver model spec

* Update PSA API specification to 1.0.0 * Update Mbed Crypto references to Mbed TLS * Remove old, unlinked copy of the PSA driver model spec

yanesca commented

2020-04-17 12:24:36 -05:00

(Migrated from github.com)

I can confirm that the files in the _sources directory match if that helps.

I can approve if you find this satisfying, but I would prefer to have some more confidence. Could you perhaps generate the documentation with the docker image and update the PR? I would hope that it would lead to identical or close to identical results on both of our systems. Or do you have an idea how this could be reviewed better?

I can see that the two last commits are correct, but I have hard time reviewing the first one. I built the html documentation with the docker image, but you seem to have newer version of sphinx installed. Because of this there is a huge diff, mostly .css and .js, and they should be more or less safe to ignore, but there is tons of inline formatting and it would be very time consuming to verify if there was change in the text. I can confirm that the files in the `_sources` directory match if that helps. I can approve if you find this satisfying, but I would prefer to have some more confidence. Could you perhaps generate the documentation with the docker image and update the PR? I would hope that it would lead to identical or close to identical results on both of our systems. Or do you have an idea how this could be reviewed better?

gilles-peskine-arm commented

2020-04-17 12:29:31 -05:00

(Migrated from github.com)

Good point. I'll re-generate the files in the official Docker environment.

gilles-peskine-arm commented

2020-04-17 14:00:01 -05:00

(Migrated from github.com)

Regenerated. I also updated the version in index.html, I'd forgotten to do that earlier.

yanesca commented

2020-04-20 07:42:33 -05:00

(Migrated from github.com)

Have you regenerated the .pdf as well? (I can see many differences, the ones I checked are only alignment, but diff-pdf shows a lot of them and it would be really time consuming to go through all of them.)

Thank you, now the html is almost identical, the only difference is that there are couple of unused files in this PR: html/_static/documentation_options.js html/_static/jquery-3.2.1.js html/_static/language_data.js html/_static/underscore-1.3.1.js Have you regenerated the .pdf as well? (I can see many differences, the ones I checked are only alignment, but diff-pdf shows a lot of them and it would be really time consuming to go through all of them.)

gilles-peskine-arm commented

2020-04-20 08:15:37 -05:00

(Migrated from github.com)

I don't know what happened with the PDF. It had identical contents but slightly different formatting, so I must have used one from a different run with a different version of Sphinx. I've amended it again, and I made sure to copy the PDF from the same build tree as the HTML files.

I had amended the commit without paying attention to the changed set of support files, which explains why the files that were present in the original were still present in the amended version. I've amended the commit again to remove those files. I don't know what happened with the PDF. It had identical contents but slightly different formatting, so I must have used one from a different run with a different version of Sphinx. I've amended it again, and I made sure to copy the PDF from the same build tree as the HTML files.

gilles-peskine-arm commented

2020-04-20 08:17:09 -05:00

(Migrated from github.com)

It's unfortunate that we don't have an official CI build for the spec. There's actually an official PDF, but for some reason it isn't getting generated on the psa-crypto-api-1.0.0 tag (in the private psa-crypto-api repository), there seems to be something wrong with the CI script.

It's unfortunate that we don't have an official CI build for the spec. There's actually an official PDF, but for some reason it isn't getting generated on the `psa-crypto-api-1.0.0` tag (in the private `psa-crypto-api` repository), there seems to be something wrong with the CI script.

yanesca (Migrated from github.com) approved these changes

2020-04-20 10:39:15 -05:00

yanesca (Migrated from github.com) left a comment