[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        |   Resolution:
 Keywords:                 |  External ID:
---------------------------+------------------------
Description changed by jng:

Old description:

> 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:
>
>  * [x] Add helper script to acquire required documentation tools
>  * [x] Add docfx project
>  * [ ] Update IMake to support generation of PHP stub classes with
> transferred API documentation
>  * [x] 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
>  * [x] Determine a suitable static site generator that supports code
> syntax highlighting in Java, C# and PHP (we chose docfx)
>  * [x] Add a static landing site that links to the docfx, javadoc and
> doctum generated API docs
>  * [ ] Java: Document unique features of the Java binding (mine MapGuide
> RFC 129 and 185 for content)
>  * [ ] .net: Document unique features of the .net binding (mine MapGuide
> RFC 185 for content)
>  * [ ] PHP: Document the fact that `constants.php` no longer exists and
> the constant defns are now baked into the PHP extension itself
>  * [~] Add conceptual topics to the landing site
>  * [ ] Package zip of the landing site with the 3 language-specific API
> docs

New description:

 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:

  * [x] Add helper script to acquire required documentation tools
  * [x] Add docfx project
  * [ ] Update IMake to support generation of PHP stub classes with
 transferred API documentation
  * [x] 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
  * [x] Determine a suitable static site generator that supports code
 syntax highlighting in Java, C# and PHP (we chose docfx)
  * [x] Add a static landing site that links to the docfx, javadoc and
 doctum generated API docs
  * [ ] Java: Document unique features of the Java binding (mine MapGuide
 RFC 129 and 185 for content)
  * [x] .net: Document unique features of the .net binding (mine MapGuide
 RFC 185 for content)
  * [ ] PHP: Document the fact that `constants.php` no longer exists and
 the constant defns are now baked into the PHP extension itself
  * [~] 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#comment:2>
MapGuide Open Source <http://mapguide.osgeo.org/>
MapGuide Open Source Internals