search

NTNU-IHB / PythonFMU

A lightweight framework that enables the packaging of Python3.x code as co-simulation FMUs
MIT License
137 stars 38 forks source link

Add documentation #170

Closed eisDNV closed 2 months ago

markaren commented 1 year ago

Could you provide some more information about this change? Are any of the files added autogenerated? In which case it would be better to leave them out and let the user run the necessary step to generate the documentation if needed (?).

In any case, I think the README should be updated to reflect the changes and how to use it.

eisDNV commented 1 year ago

Hei,

the only changes in existing code concern updates of docstrings. Beyond that I added the folder /doc and inside there /doc/source with the files required to configure Sphinx runs. The /doc/build directory is not included on github. That means that only everything needed to generate the documentation is included, but not the files generated by Sphinx runs.

Probably we should add the following at the end of the Readme.md: '''The package includes documentation. Do the following to generate e.g. html documentation:: cd /doc make html

The documentation is then available as /doc/build/html/index.html'''

Does that answer your questions?

Siegfried

From: Lars Ivar Hatledal @.> Sent: onsdag 11. januar 2023 08:52 To: NTNU-IHB/PythonFMU @.> Cc: Eisinger, Siegfried @.>; Author @.> Subject: Re: [NTNU-IHB/PythonFMU] Add documentation (PR #170)

Could you provide some more information about this change? Are any of the files added autogenerated? In which case it would be better to leave them out and let the user run the necessary step to generate the documentation if needed (?).

In any case, I think the README should be updated to reflect the changes and how to use it.

- Reply to this email directly, view it on GitHubhttps://eur01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2FNTNU-IHB%2FPythonFMU%2Fpull%2F170%23issuecomment-1378357806&data=05%7C01%7CSiegfried.Eisinger%40DNV.com%7C642e9096ac4a451d222e08daf3a8c7f9%7Cadf10e2bb6e941d6be2fc12bb566019c%7C0%7C0%7C638090203509709553%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=PaDKRZYwkWyuEO6HEozMuGMlOwKdRd4MybL1wSw5TsE%3D&reserved=0, or unsubscribehttps://eur01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Fnotifications%2Funsubscribe-auth%2FAVQEWOJHMMFGW23DUUHGSEDWRZRDRANCNFSM6AAAAAATWWWZ6I&data=05%7C01%7CSiegfried.Eisinger%40DNV.com%7C642e9096ac4a451d222e08daf3a8c7f9%7Cadf10e2bb6e941d6be2fc12bb566019c%7C0%7C0%7C638090203509709553%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=lfLb5ucx5Fjb86nooNGCUztz%2Fck4GnundUWBJZ7lAko%3D&reserved=0. You are receiving this because you authored the thread.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.

markaren commented 2 months ago

I don't think the current state of this PR is mergable. It is not clear what sphinx does or how to use. The PR also adds duplication of files and files that need manual oversight in terms of potential code changes.

The docstrings would be acceptable as is as a separate PR.

Closing for now.

eisDNV commented 2 months ago

Ok. This pull request is rather outdated. Our current internal version has superseded that and we will make a new pull request. With respect to sphinx, this is the recommended way to document python packages and we started to improve the documentation as part of our work to understand the package. Why does sphinx represent a problem? Is it only another dependency?

markaren commented 2 months ago

It's more that the PR does not explain itself well enough. Further, doc/source/modules.rst seems to be an autogenerated file that should not be included in the PR? If it is indeed intended, then it complicates the project as it needs manual maintance. The readme file is also duplicated.