#32 LibDocScripting corner

closed
None
2020-02-08
2018-11-01
aliazzz
No

Hi Ingo,

As you allready guessed, I'd like to suggest a Tools/LibDocScripting corner in cForge.

I actually have used reStructeredText allready in several professional Libraries I wrote for my employer.
This corner could give some extra insights /tips/tools on how to produce self documenting libraries/applications and how to autogenerate .chm's or pdf (or html).

My personal experience is that beginners will have a tough understanding of the toolchain in place to generate the documentation out of the libraries/projects because the documentation on this point is somewhat "tough".

Beginners difficulties could be:
Understanding of the workflow in the toolchain in general (the picture helps a lot in the documentation, but I foresee beginners will still have trouble),
Adding CODESYS LibDocSctripting to PATH environment of windows (how to with pictures missing),
Mandatory third party installation of HTMLWorkshop to generate .chm's (not explained that well)
Mandatory third party installalion of "Sphinx" and /or "rst2pdf" python tools to generate .pdf out of either latex or .rst files (not explained well).
* Providing a "workflow" example for all the above points, which goal is to more straightforward then the help files examples (which are not that clear for newcommers) . The workflow examples in documentation (especially generating .pdf) will fail if one follows it to the letter. This has to do with assumptions in directories.

Hope you pick this up

Discussion

  • Ingo

    Ingo - 2018-11-02

    Hi Aliazzz,
    seems like you have more experience with this topic, than I have personally ;)

    For me this sounds as a good topic for a project in the tools neighborhood. As the goal can be to provide documentation + an extra package, which smoothes the workflow. I would like to assist you with packaging etc. if necessary.

     
  • aliazzz

    aliazzz - 2018-11-02

    I work with version 3.5.11.x and I saw that documentation of 3.5.13.x has evolved in an elegant way. I will use help.codesys.com to read up on the differences.

     
  • Ingo

    Ingo - 2018-11-02

    Good to hear that. If you feel, that a project makes sense, please feel free to create one. And my offer to help you with packaging, etc. persists.

     
  • Ingo

    Ingo - 2018-11-05
    • status: open --> closed
     

Log in to post a comment.