wolfHSM Manual (migration from wolfHSM-docs to wolfssl/documentation)

[aidangarske]

wolfHSM documentation generation.

The wolfHSM does not yet have API documentation, so the Doxygen steps are being skipped. Only the src/*.md files are being used for the HTML and PDF manuals.

Updated the mkdocs.yml and took out the SUMMARY.md because it is not necessary in documentations repo.

Adds new V=1 option to help with showing commands being used. Updated copyright.

[dgarske]

The failure is due to the existing #17 1.500 cat: api/md/tpm2_8h.md: No such file or directory issue. I'm going to try and fix that right now.

I locally built make wolfhsm and got the error:

1.661 pandoc: SUMMARY.md: withBinaryFile: does not exist (No such file or directory)

wolfHSM-Manual.pdf

Fix pushed. Attached is the wolfHSM User Manual for review.

[bigbrett]

Awesome! First quick pass flagging some broken links, spelling errors, and a few suggestions.

[bigbrett]

broken link, but this section doesn't exist. I can add it in a PR later

[bigbrett]

@aidangarske You mentioned that we don't yet have doxygen - we do have the client and server APIs doxygen-commented, but it is inline in the source code (as opposed to maintained separately like wolfSSL does in this repo). There isnt a doxyfile yet though. Just FYI on where that is at

[dgarske]

@aidangarske You mentioned that we don't yet have doxygen - we do have the client and server APIs doxygen-commented, but it is inline in the source code (as opposed to maintained separately like wolfSSL does in this repo). There isnt a doxyfile yet though. Just FYI on where that is at

@aidangarske is OOO today, but @rlm2002 can help. Brett if you have API's that are public that you would like Doxygen to process please provide a link to those. Aidan and I could not find them.

/*!
    \ingroup Client Functions
    \brief Description of function

    \return 0=

    \param arg1 description 

    _Example_
    \code
    int rc = CallFunc();
    \endcode

    \sa OtherFunction
*/

Thanks

[bigbrett]

@aidangarske You mentioned that we don't yet have doxygen - we do have the client and server APIs doxygen-commented, but it is inline in the source code (as opposed to maintained separately like wolfSSL does in this repo). There isnt a doxyfile yet though. Just FYI on where that is at

@aidangarske is OOO today, but @rlm2002 can help. Brett if you have API's that are public that you would like Doxygen to process please provide a link to those. Aidan and I could not find them.

@rlm2002 here ya go. We haven't set up the client/server groups yet

• client API: https://github.com/wolfSSL/wolfHSM/blob/main/wolfhsm/wh_client.h
• server API: https://github.com/wolfSSL/wolfHSM/blob/main/wolfhsm/wh_server.h

[JacobBarthelmeh]

Changes look good to me as a nice first step to adding the wolfHSM manual. The github actions is complaining about:

> [wolfssl-stage1 2/2] RUN make pdf V=:
0.992 [info] Loading docs/xml/wh__flash_8h.xml
0.992 [info] Loading docs/xml/wh__error_8h.xml
Warning: 0.993 [warning] Failed to parse member wh__error_8h error: basic_string: construction from null is not valid
0.993 [info] Loading docs/xml/wh__common_8h.xml
Warning: 0.994 [warning] Failed to parse member wh__common_8h error: basic_string: construction from null is not valid
0.994 [info] Loading docs/xml/README_8md.xml

[dgarske]

Changes look good to me as a nice first step to adding the wolfHSM manual. The github actions is complaining about:

> [wolfssl-stage1 2/2] RUN make pdf V=:
0.992 [info] Loading docs/xml/wh__flash_8h.xml
0.992 [info] Loading docs/xml/wh__error_8h.xml
Warning: 0.993 [warning] Failed to parse member wh__error_8h error: basic_string: construction from null is not valid
0.993 [info] Loading docs/xml/wh__common_8h.xml
Warning: 0.994 [warning] Failed to parse member wh__common_8h error: basic_string: construction from null is not valid
0.994 [info] Loading docs/xml/README_8md.xml

Those are fixed with wolfSSL/wolfHSM#42
Caused by unnamed enums and unions.
Once that PR is merged this should work. I've tested locally.

[JacobBarthelmeh]

@bigbrett is the request for changes still outstanding? Am okay merging in this initial documentation addition as is.

[bigbrett]

@bigbrett is the request for changes still outstanding? Am okay merging in this initial documentation addition as is.

@JacobBarthelmeh let me take a peek. I'll approve if they are all addressed, otherwise I'll request changes.

[bigbrett]

@JacobBarthelmeh good to go.

@dgarske @aidangarske thank you both so much for your help on this. Go Team Garske!!!

@dgarske @JacobBarthelmeh Regarding the doxybook2 error, naming the enums is fine, but naming the unions will require changes to the calling code to work. We might end up doing that, or we may just pull docs into a separate header like wolfSSL does. Will discuss with the team. I don't think anonymous unions are critical to funcitonality, so we might just bite the bullet and refactor in this case. I'll keep you in the loop, but go ahead and merge for now without the API docs live.