74 update generated docs

[StephanieKemna]

Description

Resolves #74

Cleaning the docs; remove stuff that seems unnecessary, add missing pages, add missing info.

How Has This Been Tested?

• in docs: make html
• start build\html\index.html

Screenshots (if appropriate)

Developer Checklist (before requesting PR review)

• My code follows the style guidelines of this project
• My changes generate no new warnings
• [n/a] Any dependent changes have been merged and published in downstream modules

I have:

• commented my code, particularly in hard-to-understand areas
• performed a self-review of my own code
• not committed unnecessary formatting changes, thereby occluding the actual changes (e.g. change of tab spacing, eol, etc.)
• made corresponding changes to the documentation
• added change to CHANGELOG.md
• [n/a] added tests that prove my fix is effective or that my feature works (for core features)

Reviewer checklist

I have:

• have performed a review of the code
• tested that the software still works as expected
• checked updates to documentation
• checked that the CHANGELOG is updated

[StephanieKemna]

@ClaasRostock can you have a look at this? wondering whether there was any point to the automodule rst files - they did not seem to generate anything good, so I have removed them. But maybe they should've been set up properly.
There are still a bunch of warnings w.r.t. duplicate stuff, example:
..\src\mlfmu\types\onnx_model.py:docstring of mlfmu.types.onnx_model.ONNXModel.state_size:1: WARNING: duplicate object description of mlfmu.types.onnx_model.ONNXModel.state_size, other instance in _autosummary/mlfmu.types.onnx_model.ONNXModel, use :no-index: for one of them
which I think is due to the autosummary stuff. Not sure if this needs to be resolved or we always have this?

I found some online docs saying this can happen if you have multiple automodule - but I removed automodule rst files, but maybe autosummary creates that?

Do the docs, as I have made them now, look alright? Anything we are missing and should add?

[ClaasRostock]

Hi Stephanie,

the autosummary Sphinx extension was introduced by David @davidhjp01 in the TDR_rax repo, and honestly I just applied that change also in MLFMU without thinking much about it.
So, it seems now has come a time to look at it at more detail :-).
Let's do so and look into it next week. Maybe you, @davidhjp01 , have any additional input? Otherwise let's just check how we best get the docs build, and if autosummary turns out to stand in way by any reason, then we should be able to also remove it again. Or learn how we can make it do what we want it to :-)

[StephanieKemna]

Hi Stephanie,

the autosummary Sphinx extension was introduced by David @davidhjp01 in the TDR_rax repo, and honestly I just applied that change also in MLFMU without thinking much about it. So, it seems now has come a time to look at it at more detail :-). Let's do so and look into it next week. Maybe you, @davidhjp01 , have any additional input? Otherwise let's just check how we best get the docs build, and if autosummary turns out to stand in way by any reason, then we should be able to also remove it again. Or learn how we can make it do what we want it to :-)

The autosummary is giving warnings, but it is the main source of documentation now. That seems to work nicely.
The automodule stuff did not autogenerate a bunch of documentation in the same fashion, so I removed that. Since I figured we did not need both, and the autosummary docs seemed sufficient to me. But I don't know if that's what the docs 'usually' look like and if we consider it sufficient or not.

[davidhjp01]

Just had a brief look, try to remove Methods section for class declarations. Seems we do not need it and it conflicts with the docstrings of corresponding methods.

[StephanieKemna]

[like] Kemna, Stephanie reacted to your message:

…

________________________________ From: David Heejong Park ***@***.***> Sent: Monday, November 4, 2024 7:53:16 AM To: dnv-innersource/mlfmu ***@***.***> Cc: Kemna, Stephanie ***@***.***>; Assign ***@***.***> Subject: Re: [dnv-innersource/mlfmu] 74 update generated docs (PR #73) Caution: This email originated from outside of the DNV Organization. Do not click links or open attachments unless you recognize the sender and know the content is safe. Just had a brief look, try to remove Methods section for class declarations. Seems we do not need it and it conflicts with the docstrings of corresponding methods. — Reply to this email directly, view it on GitHub<#73 (comment)>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/ABRXMLMSLLA7ECTRPULL7X3Z64RWZAVCNFSM6AAAAABRA67TN6VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDINJUGAZDKMRXGQ>. You are receiving this because you were assigned.Message ID: ***@***.***> ************************************************************************************** This e-mail and any attachments thereto may contain confidential information and/or information protected by intellectual property rights for the exclusive attention of the intended addressees named above. If you have received this transmission in error, please immediately notify the sender by return e-mail and delete this message and its attachments. Unauthorized use, copying or further full or partial distribution of this e-mail or its contents is prohibited. **************************************************************************************

[ClaasRostock]

made some proposals in a separate PR (meant to be merged into this one, if ok with you)

[ClaasRostock]

Ah, one more thing: When applying the changes proposed in my PR, you might need to delete all .rst files in your docs/source/_autosummary folder.

It seems that rebuilding the docs (via ./docs/make.bat html) does create any new rst files in that directory, but does not delete any .rst files which are orphaned.

[ClaasRostock]

@ClaasRostock can you have a look at this? wondering whether there was any point to the automodule rst files - they did not seem to generate anything good, so I have removed them. But maybe they should've been set up properly. There are still a bunch of warnings w.r.t. duplicate stuff, example: ..\src\mlfmu\types\onnx_model.py:docstring of mlfmu.types.onnx_model.ONNXModel.state_size:1: WARNING: duplicate object description of mlfmu.types.onnx_model.ONNXModel.state_size, other instance in _autosummary/mlfmu.types.onnx_model.ONNXModel, use :no-index: for one of them which I think is due to the autosummary stuff. Not sure if this needs to be resolved or we always have this?

I found some online docs saying this can happen if you have multiple automodule - but I removed automodule rst files, but maybe autosummary creates that?

Do the docs, as I have made them now, look alright? Anything we are missing and should add?

@StephanieKemna @davidhjp01
I found a solution to above problem. Solved with latest commit in PR #74 , branch 74-update-generated-docs-review-claas (51a291e).
If you merge PR #74 into 74-update-generated-docs, then this PR #73 is from my point of view good to go.

[StephanieKemna]

Remaining tasks: #72 (comment)