Opened 14 months ago
Last modified 14 months ago
#2877 assigned task
Drop doxygen and use per-language API documentation tools — at Version 1
Reported by: | jng | Owned by: | jng |
---|---|---|---|
Priority: | low | Milestone: | 4.0 |
Component: | Documentation | Version: | |
Severity: | trivial | Keywords: | |
Cc: | External ID: |
Description (last modified by )
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:
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