With the introduction of DocC for generating documentation from source code, is it possible to take the output of DocC and use it as the source of truth for an Apple Help Book (for use inside of a macOS App)?
Running Apple DocC as a Apple Help Book file
154 Views Asked by Chris At
2
There are 2 best solutions below
0
On
Probably not. They are completely different animals. A help book is a complete web site with some help for certain kinds of anchors. A DocC is a highly restricted, formalized representation of a very specific type of information. Indeed, even if you meld the two things, you would not want to; a help book helps users, whereas DocC displays a programming API to a programmer.
Just as an example, here is a help book I wrote:
http://www.apeth.com/sd5help/index.html
You couldn't possibly express that using DocC. If the problem is that you're looking for a tool to help you write help books, DocC is not it.
@matt mentioned:
However I disagree with it. You can create article pages with DocC: Getting Started with Sloths
The problems with using DocC to create Apple Help Book:
DocC documentation only support basic markdown syntax, so your formatting option is limited.
DocC exports the documentation as a single page web app, where Apple Help Book expect individual html files for each help pages. So you would need to automatically generate static html files.
DocC documentation doesn't let you add custom meta tags for indexing or keywords and name for anchors. (Maybe you can use comments in markdown, then automatically generate them from comments. However I'm not sure if comments in markdown would remain in DocC generated file)
You would still need to use Help Indexer to index them.
@matt mentioned:
You can definitely meld the two and use DocC generated files as your source of truth, but I would rather do it with other html editors, or a better markdown editor if you prefer the markdown syntax.