Code documentation with Flare

This forum is for all Flare issues related to importing files or projects.
Post Reply
leonardopsantos
Jr. Propeller Head
Posts: 2
Joined: Wed Mar 06, 2019 9:18 am

Code documentation with Flare

Post by leonardopsantos »

Hello all! We're looking at Flare as our documentation tool, but we're not sure how to deal with code documentation. By code documentation, I mean basically what Doxygen does: parsing code and content and producing output in different formats.

We want to move away from our home-grown and use a more standardized way to document code. This pretty much means using Doxygen.

Doxygen supports Markdown, so we'd be happy with using Markdown for content and Doxygen for generating the output in HTML and PDF (through LaTeX). I already have put together a LaTeX style that we're happy with.

If we're using Doxygen to document the code, we'll want Flare to be able to read Doxygen's output. And by output, I mean Doxygen's XML (we might go the HTML way if that's easier).

So what I'd like to know is:

1) Is anyone using Flare to document code? How to go about it?
2) Do we need to use Doxygen for (1), or is there a better way that plays nicer with Flare and doesn't make the developer's life miserable?
3) Should we give up on trying to use Flare as the one single tool for documentation and just use Doxygen for documents that deal with code (API documentation, user guides)?

I already read this post, but it's quite old (2012) and I don't feel that importing Doxygen's HTML output into Flare is the right way to do it.

Why We Jumped From DITA and Doxygen to MadCap Flare is pretty similar do what we need, but not quite. We want HTML + PDF output. We don't necessarily need HTML5. API documentation doesn't have to be funky, it has to be easy to read and the information should be readily available.

Any help is more than welcome!

Thank you.
Nita Beck
Senior Propellus Maximus
Posts: 3667
Joined: Thu Feb 02, 2006 9:57 am
Location: Pittsford, NY

Re: Code documentation with Flare

Post by Nita Beck »

Welcome to the forums, Leonard! :)

I actually don’t have a ready answer for you, from my personal experience. I just want to mention that you might want to post a similar inquiry in the Write The Docs community on Slack. That community is heavily about code documentation, with lots of different tools discussed, including Flare. I suggest you post in their #doctools channel.

Anyone else here in the forums who maybe could answer our new friend’s questions?
Nita
Image
RETIRED, but still fond of all the Flare friends I've made. See you around now and then!
Post Reply