Basic setup to customize markdown doc

[dogboydog]

It was requested to make this a PR even though I haven't made too much progress with this. What I can share is the basic setup and process for iterating with the typedoc-plugin-markdown generation.

One time setup

• Clone typedoc-plugin-markdown. The rest of the instructions assume you clone it alongside your local copy of Tiled.
• Install Yarn if you don't already have it. The markdown plugin uses Yarn to build.
• cd to your clone of the plugin /packages/typedoc-plugin-markdown and issue yarn install to install the dependencies

Iterating on the markdown output

• Start the ./_source/serve.sh script on your copy of the gh-pages branch of tiled.

This string of commands will build and package the plugin as a .tgz file and install that into the scripting-doc directory's node_modules. Change ../../../gh-pages to the location of your copy of the gh-pages branch of tiled. These commands also assume you cloned the plugin in the same parent directory as your copy of tiled.

cd ../../../typedoc-plugin-markdown/packages/typedoc-plugin-markdown/ && yarn run build && yarn pack && cd ../../../tiled/docs/scripting-doc/ && rm -rf package-lock.json node_modules/typedoc-plugin-markdown && npm install && ./generate-scripting-tsdoc.sh ../../../gh-pages/

• The main thing you want to change in the plugin repository is the .hbs files under packages/typedoc-plugin-markdown/src/resources/partials Running the above string of commands will make the changes take effect.

• Visit yourlocal-gh-pages-tiled-server/docs/scripting/README in a web browser to see the output. I didn't overwrite the current scripting doc with this setup.

Notes

• One of the goals was to consolidate the information into tables rather than paragraphs with lots of line breaks. To fully achieve this you might have to edit some of the .ts files in the markdown plugin as well. There are a lot of different pieces of information that are combined in the output that make it hard to process them into a single cell of a table but I'm sure someone can do it
• On removing extra whitespace from the output, it may be useful to look into the tilde syntax of Handlebars. My prototypes surrounded many of the Handlebars expressions with this to trim down the output.

Please change the target branch to a branch where you want to look at this rather than master

[bjorn]

I've started to make some initial changes to the output to make it more dense. Still a long way from being actually usable, unfortunately.

[dogboydog]

Yes, sorry it's not much to work with

[bjorn]

Yes, sorry it's not much to work with

No need to feel sorry, it helped anyway to continue from your work! I'll try to list the remaining issues that we'd need to address:

• Properties should probably render to a table, similar to how function parameters used to render to a table. That would take up a lot less space.
• "Namespace:", "Class:" and "Interface:" prefixes should be removed.
• Functions with multiple signatures need to be written out multiple times (maybe should drop signatureTitle instead)
• The "since 1.4" kind of information should ideally be inline and posslbly right-aligned, if possible in Markdown (maybe with embedded HTML?).
• Instead of rendering full class hierarchies, only mention "inherits Foo" in the description.
• Potentially descriptions should use blockquotes, to make the whole thing more readable than when everything is left-aligned.

I still have my doubts whether it will in the end be dense enough to have everything on a single page, though.