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

Posted on

Upcoming viewport manual

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]
  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.


  • 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.

Start the discussion at Castle Game Engine Forum