New development for us - need to incorporate auto generated docs

Please post all questions and comments regarding Help & Manual 7 here.

Moderators: Alexander Halser, Tim Green

Post Reply
Dave Gehman
Posts: 575
Joined: Sat Sep 23, 2017 9:05 pm

New development for us - need to incorporate auto generated docs

Unread post by Dave Gehman »

Our development group has created an automated system for generating documentation as new code is written. Right now, it consists of documentation for all of the basic objects in our software. The software's overall WebHelp documentation covers many other things as well.

The automated output is formatted ('published' in H+M nomenclature) in the form of a web site, with Index.html serving as the TOC. In Chrome, it looks like this:
Image

I brought the whole shebang into H+M, which did a passable job with automatic import, where the tree looks like this:
Image

Clearly I have to do some work. The TOC in the H+M project is a non-linked list of the topics that H+M put under it, and the TOC of the auto-doc HTML site (index.html) has been auto-named "Base Library docs | Base Library Docs" -- plus, there is that suffix of "| Base Library docs" on names in the tree.

But the main questions are below:

Can this ever-changing (i.e. dynamic) auto-documentation be integrated into our overall H+M project?

If so, what's the best way?
  • Links to the content on our server?
  • Import into H+M, which is then integrated into the overall docs in the original H+M project (and how)?
  • Is this a use of multiple TOCs?
Is there a way to make this auto-documentation content dynamic on-line? - that is, automatically kept up to date as the developer's HTML site is changes?
  • Probably not, since it is dynamic...
  • but it would be VERY useful to have the integrated material automatically -- or easily -- updated just prior to publishing a new rev. of the overall docs.
User avatar
Tim Green
Site Admin
Posts: 23156
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany
Contact:

Re: New development for us - need to incorporate auto generated docs

Unread post by Tim Green »

Hi Dave,
Can this ever-changing (i.e. dynamic) auto-documentation be integrated into our overall H+M project?
Yes, but not the way you're doing it now. As you've already discovered, re-importing the HTML on an ongoing basis would be problematic.

Since you're already auto-generating HTML, why not auto-generate Help+Manual XML topics instead? You could then also generate the chapter structure along with it. Changes would then update automatically and you could perform any necessary editing directly in Help+Manual before generating the new HTML version.

The Help & Manual XML format is fully documented in the Helpman_XML_ref.chm file, which you can find in the Help & Manual program directory.

This tutorial is a little out of date but it explains the basic principles and how it works, you would just need to check the current schema reference when implementing anything described there:

https://helpman.it-authoring.com/viewto ... f=2&t=5145
Regards,
Tim (EC Software Documentation & User Support)

Private support:
Please do not email or PM me with private support requests -- post to the forum directly.
Dave Gehman
Posts: 575
Joined: Sat Sep 23, 2017 9:05 pm

Re: New development for us - need to incorporate auto generated docs

Unread post by Dave Gehman »

Tim Green wrote: Wed Feb 19, 2020 9:46 am .... Since you're already auto-generating HTML, why not auto-generate Help+Manual XML topics instead? You could then also generate the chapter structure along with it. Changes would then update automatically and you could perform any necessary editing directly in Help+Manual before generating the new HTML version....
Auto-generating H+M-formatted XML is clearly the best answer -- or, rather, the answer that makes my life easy.

I'll meet with the development group to see if this is feasible. I have a feeling that it will not be: their output is not H+M centric. It's objective is to be dovetailed easily into our online mechanical engineering software and thus is currently designed to fit seamlessly into that software's HTML, XML, JavaScript, and JSON world.

Given the possibility that it will remain a "foreign" (independent) HTML/XML website rather than an H+M compliant site, I think I'll have to approach this as a need to map an external resource to H+M. Now that I articulate this, I see that it's far from, say, bringing a resource like a video into our H+M project. All the work to translate a video resource into H+M has already been done by H+M developers. And it's in H+M because it's a commercially-viable feature that appeals to many help documentation developers, where integration into our online software would please only a market of one.

(Of course, with the proliferation of cloud-based software, all of which requires documentation, user tools to map randomly-formatted Web to H+M XML might appear on your radar. A whole lot of the engine has been done -- it's what goes on behind the scenes when people like me click "Regular HTML and text files" on the New project > start > "Import existing documentation to a new project" dialog. The non-trivial addition of user-controlled options and switches is "all" that needs to be done -- "all" in quotes because that's a major undertaking. Just trying to plant a seed :wink: ).
User avatar
Tim Green
Site Admin
Posts: 23156
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany
Contact:

Re: New development for us - need to incorporate auto generated docs

Unread post by Tim Green »

Hi Dave,

If you can get by without actually editing the HTML you are including in your project, your next best option would be to embed it in topics with the #MERGE keyword:

https://www.helpandmanual.com/help/hm_w ... ting+topic

See the section "Inserting external HTML files with a code object"
Regards,
Tim (EC Software Documentation & User Support)

Private support:
Please do not email or PM me with private support requests -- post to the forum directly.
Dave Gehman
Posts: 575
Joined: Sat Sep 23, 2017 9:05 pm

Re: New development for us - need to incorporate auto generated docs

Unread post by Dave Gehman »

Thanks, I'll explore that.
Post Reply