[Mapguide-trac] [mapguide-trac] #2877: Drop doxygen and use per-language API documentation tools

[MapGuide Open Source]

#2877: Drop doxygen and use per-language API documentation tools
-----------------------------+----------------------
   Reporter:  jng            |      Owner:  jng
       Type:  task           |     Status:  assigned
   Priority:  low            |  Milestone:  4.0
  Component:  Documentation  |    Version:
   Severity:  trivial        |   Keywords:
External ID:                 |
-----------------------------+----------------------
 Doxygen is currently our API doc generation tool, which is not suitable
 for our API documentation needs due to its C++-centric nature and our
 downstream API consumers being the 3 managed language bindings to this C++
 API.

 Instead, we should generate API documentation for each language target in
 their preferred documentation tool of choice and implement a static
 landing page that links to all 3 generated API docs.

 For this, we will use the following tools for each respective language
 target:

  * PHP: [https://github.com/code-lts/doctum doctum]
  * .net: [https://dotnet.github.io/docfx/ docfx]
  * Java: The built-in `javadoc` that comes with the JDK

 Thanks to the support in IMake for transferring API doc fragments to the
 .net and Java proxy classes implemented a long time ago, most of the hard
 work is already done for us. The only gap is PHP, where we will require
 IMake to generate stub PHP proxy classes (with transferred API doc
 fragments) for the purpose of running doctum against it.

 With this in place, we can drop doxygen and all of its associated files
 from our source tree.

 Task breakdown:

  * [ ] Add helper script to acquire required documentation tools
  * [ ] Add docfx project
  * [ ] Update IMake to support generation of PHP stub classes with
 transferred API documentation
  * [ ] Add top-level doc build script to run docfx, javadoc and doctum
 against their respective proxy class source files
  * [ ] Convert all doxygen conceptual topics over to markdown .md files
  * [ ] Determine a suitable static site generator that supports code
 syntax highlighting in Java, C# and PHP
  * [ ] Add a static landing site that links to the docfx, javadoc and
 doctum generated API docs
  * [ ] Add conceptual topics to the landing site
  * [ ] Package zip of the landing site with the 3 language-specific API
 docs
-- 
Ticket URL: <https://trac.osgeo.org/mapguide/ticket/2877>
MapGuide Open Source <http://mapguide.osgeo.org/>
MapGuide Open Source Internals