Re: integrating authored content with generated API docs

[Robert Lauriston <robert -at- lauriston -dot- com>]

Importing javadoc or Doxygen XML output into Confluence would take
more than just a bit of XSLT.

Integrating it with a structured FrameMaker or Oxygen project might be simpler.

There are a lot of XML development tools you don't have to pay for up
front, but total cost of ownership for an open-ended custom
development project can be several orders of magnitude higher than
customizing an off-the-shelf tool that already does 90% of what's
required.

On Sat, May 28, 2016 at 6:42 AM,  <mbaker -at- analecta -dot- com> wrote:
> Actually, it can be trivial depending on the tools you are using for the
> rest of your documentation.
>
> Both JavaDoc and Doxygen can output to XML rather than HTML. So if you are
> using an XML based tool chain, or any tool that can import XML, or any tool
> that has a text-based input format you can create from XML, or can import
> content from any application that itself has an XML-based or text-based
> input format that you can create from XML, then it is simply a matter of
> writing a bit of XSLT to do the necessary transformation.
>
> More interesting is the next level up the integration ladder, which is to
> merge content written outside of the codebase with the material extracted
> from the code base at the topic level (in other words, compose a topic from
> a combination of extracted and externally authored content) and to do
> automatic linking between the API docs and the rest of the doc set.
>
> Basic XML transformation is the key that unlocks a thousand doors. The tools
> are free, reasonably high level, and well documented. So many docs problems
> become so much simpler with these simple tools in hand.
>
> Mark
>
>
>
> -----Original Message-----
> From: techwr-l-bounces+mbaker=analecta -dot- com -at- lists -dot- techwr-l -dot- com
> [mailto:techwr-l-bounces+mbaker=analecta -dot- com -at- lists -dot- techwr-l -dot- com] On Behalf
> Of Tom Johnson
> Sent: Friday, May 27, 2016 3:38 PM
> To: Robert Fekete
> Cc: TECHWR-L Writing
> Subject: Re: integrating authored content with generated API docs
>
> This site is a jekyll-swagger hybrid that incorporates generated API docs:
> https://developer.epages.com/apps/
>
> I'm not sure how it was built, though.
>
> As far as integrating Javadoc or Doxygen outputs into another output, I'd
> say give up this effort now. It's pretty much impossible beyond adding some
> pages in Doxygen.
>
> Tom
>
> ---------------------
> blog: idratherbewriting.com
> twitter: tomjohnson
> email: tomjohnson1492 -at- gmail -dot- com
> cell: 408-540-8562
>
> On Fri, May 27, 2016 at 11:24 AM, Robert Fekete <fekete77 -dot- robert -at- gmail -dot- com>
> wrote:
>
>> Hi,
>>
>> depending on what programming language your API is, you might try to
>> look for something similar to Sphinx for Python (
>> http://www.sphinx-doc.org/en/stable/)
>> It can autogenerate docs from code comments, and you can also add
>> static pages (and IIRC, also some structure).
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Visit TechWhirl for the latest on content technology, content strategy and content development | http://techwhirl.com

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot- 

To unsubscribe send a blank email to
techwr-l-leave -at- lists -dot- techwr-l -dot- com


Send administrative questions to admin -at- techwr-l -dot- com -dot-  Visit
http://www.techwhirl.com/email-discussion-groups/ for more resources and info.

Looking for articles on Technical Communications?  Head over to our online magazine at http://techwhirl.com

Looking for the archived Techwr-l email discussions?  Search our public email archives @ http://techwr-l.com/archives