doc: generating apidoc and userguide for TcLog

[seehma]

Hi, we created a service to automatically generate a userguide (which has to be created) and a API doc (which will be created out of your code in TcLog -> see here for guidelines: https://doc.zeugwerk.dev/contribute/contribute_documentation.html). So there is no need for a separated documentation beside your code, you can document right IN your code, where it is the most useful. We are currently in a testing phase and have of course our framework build with it (see: https://doc.zeugwerk.dev/reference/ZAux/StringBuilder/StringBuilder.html) and some other public projects like Struckig. This github action will be triggered everytime when you do a commit, then it will trigger our CI/CD system, this will pull the current repository, build the included documentation and then upload the documentation to your github repository. (see here, i have made an example: http://seehma.github.io/TcLog). For public (github) projects we made 30 triggered actions per months for free. If you like, your project can use it, there are only a few steps to be taken - see here for the documentation on this https://github.com/Zeugwerk/zkdoc-action

short explanation:

• place your zeugwerk username and password as secret to your repository (i think you have also uploaded to twinpack, so you can use this username/password combination)
• create a deploy secret and place id in your repository (see link above on how to do that)
• have fun with a completely in-code-generated api doc for TwinCAT

If there are any problems, feel free to ask. Regards M.

[seehma]

Hi @bengeisler , if you want to let our ci/cd system generate the documentation automatically, then just change the branch name in documentation.yml to the one you merged this pull request. The documentation will then be pushed as github page to this repository. if you want to start this action manually then go to actions in this repo and start documentation action. When you merge your documentation branch in main, you can set it up, that after every commit a fresh and corresponding documentation will be generated and saved. if you have any questions, feel free to reach out to us... Regards M.

[bengeisler]

I updated the code and managed to generate and publish the documentation. It's really a nice tool, thanks!! 👍

But I still have some questions:

• The workflow seems only to run if the folder is called documentation. I'd like to call it docs, however. Is that possible? Or could you otherwise make the mandatory folder name explicit in the documentation / workflow?

• Is there a way to exclude parts of the code from the documentation? I'd like the docs to cover only the public part of the library. I think it's unnecessary to show private and internal methods and types.

• Pragmas are shown in the documentation. Is that a bug or a feature? I haven't tried placing the pragmas at the top of the file, however, maybe that mitigates it. I'll try it next time.

  

• Comments in STRUCT above the fields seem not to be added in the documentation:

  /// Configuration of TcLogCore
  TYPE LoggingConfiguration :
  STRUCT
  /// File name where the logs should be written to. Should not include path.
  FileName : Tc2_System.T_MaxString;
  /// File path where the logs should be written to. Will be prefixed to `FileName`
  FilePath : Tc2_System.T_MaxString;
  /// Whether to include the instance path of TcLog into the log message or not.
  IncludeInstancePath : BOOL;
  /// Whether to write the logs to ADS output or not.
  WriteToAds : BOOL;
  /// Rolling interval: when to create a new log file.
  RollingInterval : RollingIntervals;
  /// What is the minimum log level that gets logged?
  MinimumLevel : LogLevels;
  /// Which delimiter should be used between the different parts of the log string?
  Delimiter : STRING(1);
  /// When should old log files be deleted? Unit: days. Set it to `0` if log files should never be deleted. 
  LogFileLifespan : UINT;
  /// Format of timestamp. See `TcLogCore.TimestampFormat` for formatting options.
  TimestampFormat : STRING;
  END_STRUCT
  END_TYPE

  produces

  

• The code formatting and highlighting in the output looks rather random:

  

Do I have to indicate a specific programming language after the triple accents?

[seehma]

Here i have made a PR for this last-mentioned documentation issue: https://github.com/bengeisler/TcLog/pull/8 I will come back here, for the other questions later...

[seehma]

Here is a second PR where i fixed the struct-variable-doc: #9

[seehma]

The workflow seems only to run if the folder is called documentation. I'd like to call it docs, however. Is that possible? Or could you otherwise make the mandatory folder name explicit in the documentation / workflow?

for now, not possible. we will add this with a new parameter to our ci/cd system and reach out to you if done...

[seehma]

Pragmas are shown in the documentation. Is that a bug or a feature

We made thias as "feature", when you want to implement an interface out of that documentation and you do not see the attributes, the compiler signals a warning. Therefore we decided to include those attributes...