Castle Game Engine: Documentation macros (in AsciiDoctor, PHP and WordPress shortcodes) to easily make links to API docs and embed images

From Castle Game Engine: link to original post

Writing engine documentation is so much easier now! In progress: I’m writing important new manual chapters about using viewport within the editor. It is really easier now with AsciiDoctor + macros I describe below, the improvements to our website infrastructure were absolutely worth it.

Following my plans, I have addressed 2 “pain points” of writing documentation: easily linking to API docs and embedding images. Now in AsciiDoctor you can use macros cgeref, cgeimg to easily add a reference / images. Sample of usage:

References to API docs: 

* cgeref:TCastleScene[]
* cgeref:ApplicationProperties[]

// You don't need to care in which unit they are defined.
// You don't need to care how PasDoc generates link to them
// (using anchors, like for procedures, or special pages, like for classes).
// Uses new PasDoc PHP output.

Some images:

cgeimg::block[aaa.png|Description of AAA]
cgeimg::float[dragon_0_wire.png|Dragon,gamma_nogamma_helmet.png|Gamma Correction]
cgeimg::float[
  dragon_0_wire.png|Dragon,
  gamma_nogamma_helmet.png|Gamma Correction
]

// The thumbnails will be auto-generated. 
// The syntax is short, and just exposes the 2 image layouts we need: 
// on the side, or within the main content flow.

I wrote extensive documentation of them in cge-www README.

Analogous PHP functions cgeref, cgeimg can be used in PHP.

Analogous WordPress shortcodes cgeref, cgeimg can be used for WordPress news posts.

Future:

• We’ll keep the current separation of WordPress vs AsciiDoctor for some time. This works nicely: Use WordPress for news, use AsciiDoctor for non-news. AsciiDoctor is better for version control and grepping. WordPress is better for auto-sending to other social platforms. Maybe a different resolution of this will come one day, for now the current situation actually addresses all needs (for news and non-news) best.

• The PHP way of writing docs is obsolete. With time, we will migrate all or almost-all of our documentation to AsciiDoctor (I already wrote some EmacsLisp helpers that I’m using for this). I suspect some exceptions (like main page) may remain custom-coded in PHP, but these will be exceptions.