Documentation upgrades done lately

Lots of documentation (in particular from wiki) was reworked, simplified, updated, consolidated with other pages… See in particular:

• Build Tool
• CastleEngineManifest.xml – Syntax and Examples
• Android Services (each particular service now has a dedicated documentation page)
• iOS Services (each particular service now has a dedicated documentation page)
• glTF
• Sprite sheets
• Coding conventions
• Lots of new pages are now linked from documentation sidebar. Browse them! 🙂

We converted 100% of our GitHub wiki contents to AsciiDoctor. This was done using kramdown-asciidoc and lots of manual tweaking.

Resulting AsciiDoctor sources are here. Editing them is trivial, and the HTMLs are auto-regenerated when updating the website. Note also the text To improve this documentation just edit the source of this page in AsciiDoctor (simple wiki-like syntax)…. at the bottom of new pages, with ready links to edit each page!

We have pretty URLs for pages generated by AsciiDoctor. So now we have https://castle-engine.io/build_tool instead of previous https://github.com/castle-engine/castle-engine/wiki/Build-Tool.

We also have nicer “404 not found” page now, try it: https://castle-engine.io/not_existing.

Why?

I was thinking lately of updates to our documentation. They come down to 2 big things:

1. Main page rework, to emphasize all our features using screenshots.

   For this, it is obvious I should just follow one of the numerous templates. We already use WordPress (for news) and own theme using Bootstrap. So we can easily adapt one of the numerous WordPress / bare Bootstrap templates.

2. Lots of manual updates, to document the fact that you can (and should, in simple cases) do many of the basic things using the editor. E.g. current manual describes usage of TCastleScene from code (and disregarding typical cross-platform app organization, that we advise). It should instead describe using TCastleScene from editor, and from code too, and placing most stuff in TUIState instances.

   I can pinpoint some pain-points of editing current docs in our PHP website:

   1. Writing API references is tiresome (need to spell out part of the generated URL).

   2. Adding images is tiresome (it breaks the workflow, to add new image, which is troublesome as lots of manual pages should get more screenshots).

   3. Formatting is a bit tiresome, and in effect we had docs spread between manual PHP/HTML and GitHub wiki.

Thoughts: Various approaches to documentation

I used a number of approaches for online documentation throughout my life, and within CGE.

• DocBook (e.g. for compositing shaders (to both HTML and PDF), my Ph.D thesis),

• LaTeX (e.g. for shadow maps paper).

• AsciiDoctor: I used this for modern Pascal introduction, sources on GitHub.

  This is very comfortable for editing, markup language is wiki-like (but can be processed reliably by more tools, as AsciiDoctor is more standardized than Markdown).

  The output is customizable, so it can be made to fit within a website.

• Jekyll (I used it for PasDoc website):

  + excellent version control integration, you commit markup (e.g. using Markdown or AsciiDoctor) to version control

  + secure: you just generate HTML, and put it on your website. No need for server-side or client-side scripting, when you can just put HTMLs on your website, when all you need is a static website.

• News using WordPress: WordPress is good, esp. I like

  + customizable shortcodes (e.g. to solve the “easy way to add API docs links”)

  + easy way to edit news

  + easy way to upload images

  My main concern of doing 100% content in WordPress is that you don’t have version-control support. While WordPress has versioning, it is nowhere as comfortable as “just a bunch of text files in a GIT repo”.

  + we want to use existing templates for WordPress sites. So using WordPress is beneficial to be able to use existing themes.

• GitHub wiki:

  + easy to use mark-up language, as above

  – lack of ways to customize it, looks like alien when mixed with our website

  – cannot add images, you have to upload them to normal website manually anyway. So adding images is least comfortable in this case, which makes it a “no-go” for our documentation that should have lots of screenshots.

  – lack of http redirects

• Our website using hand-crafted PHP with theme based on Bootstrap, which is our current main way to write website:

  + 100% flexible

  + PHP performed some part of “customizable shortcodes” that we need

  + looks native, we do what we want, using common theme, manual headers, automatic ToCs etc.

  – still some work to add new images, this is tiresome when writing documentation with lots of screenshots. You put them in htdocs/images/original_size, run make, add PHP/HTML code to include them.

We need to make improvements:

1. easy uploading images to current cge-www images/ , autogenerate their thumbnails

   This can be extension of current PHP code.

   A tag that adds images, and allows to upload image also in special website mode.

2. easy shortcode to add API docs.

   This can be extension of current PHP code (apidoc can be easier, to take auto-generated PHP table of Pascal identifiers). We already have PHP function used like <?php api_link('TCastleScene', 'CastleScene.TCastleScene.html'); ?>, we need to make it less tiresome, so that I can write just <?php api_link('TCastleScene'); ?> and it will find in what unit it is.

   Then it can be a WordPress shortcode too.

3. One markup, comfortable. Also replace GitHub wiki with it.

   My choice: AsciiDoctor, this proved right for modern Pascal introduction and later for
   PasDoc website. The fact that Khronos decided to use it for glTF specification is an outside confirmation that it’s good.

   Markdown can be converted to it using https://github.com/asciidoctor/kramdown-asciidoc + some manual tweaking for one-time conversion.

I hope you find these thoughts useful 🙂 These plans have been followed by actions — see section Documentation upgrades done lately above.

Please support the engine development on our Patreon. It funds development of the engine, including the efforts to document it perfectly.