CODEWITHSUNDEEP
documentationpython-sphinx
Ido Ran
Ido Ran

Reputation: 11384

Documentation for multi-programming-language API

I'm part of team working on SDK that is exposed with several programming languages - currently ObjC, C#, ActionScript, Java (Android) and later we'll have even more languages.

We want to have documentation which is made up of two parts:

  1. Human readable documentation
  2. API Reference

There are links between the two parts: from human readable docs we have links to specific classes or methods and from the API reference we may link to a document that explain the context in which the class or method is used.

We are currently use a combination of sphinx for human readable documentation and language specific tools for API such as doxygen or asdoc

I saw in LeapMotion they were able to generate a complete documentation for multiple programming-language (not human language) with cross links between programming-languages.

The Question

Does someone know how to accomplish such documentation system in a way we'll not have to duplicate each change in human readable docs to every language and have cross links between the languages?

Upvotes: 5

Views: 1880

Answers (2)

Charles Ward
Charles Ward

Reputation: 1388

I put together the Leap Motion documentation. I use Sphinx to create the package of docs and Breathe, a Sphinx plug-in, to basically import XML files generated by Doxygen into the Sphinx project for the doxygenated API references (C++, C#, Java, and Objective-C). For links from the so-called "human-readable" pages to the API references, I generate RST substitutions from the .tag files which Doxygen will generate for you. Links from the API reference to the "human-readable" pages are normal, relative hyperlinks (which I should add more of).

I use the conditional content features of Sphinx to generate a separate set of docs (both "human-readable" and API) for each programming language. Thus these articles can be customized for each programming language where needed and have the correct code examples for the current language. Because each doc set has the same structure, it isn't hard to switch from one language to another.

I did add some custom JavaScript to the page templates to help switch between languages.

tl;dr: Sphinx, Breathe, Doxygen and a small amount of custom JavaScript.

If you would like to discuss this further, you can post a question to our (Leap Motion) developer forum. I'll see it (Stackoverflow isn't the proper place for an ongoing discussion).

Upvotes: 5

Dharani Kumar
Dharani Kumar

Reputation: 457

Hi Ido Ran, Tools which you've specified are best in industry for documentation purpose,I am afraid there is no such tool yet which could provide both human and as well as API reference.Out of all my personal best is doxygen which is slighly of multi-use (human and API)..Hope this helps.

Upvotes: 2

Related Questions