2.0 documentation

[Himeko7]

Is there any up to date documentation for 2.0? i.e https://graphics32.github.io/Docs/Overview/Changes.htm is stuck at 1.9.1 from 2012. It would be nice to have a document explaining the transition from TPolygon32 to the new routines.

[andersmelander]

There isn't any documentation updates because nobody has had time to write it :-(

The problem with the current documentation system is that it is based on custom command line tools and "hand edited" text files which makes it pretty unmaintainable. It might have been fine in the last century but today nobody has time for that stuff.

A better/more modern solution would be to use an online wiki for the documentation. That way everybody could contribute whenever they felt like it. Unfortunately GitHub's wiki system is very limited (it's basically just markdown files) so it isn't really suited for our needs.

As an experiment I've been migrating the documentation to WordPress. The idea is to maintain the documentation in WordPress and then use a plugin to generate a static site from that. The static site can then be distributed as a set of html/css/js files or perhaps even as a compiled html (chm) help file.
Alas, while the pure WordPress stuff works great, the static site generator seems to have problems with the environment I'm running WordPress in (LocalWP) so there has been little progress.

[luebbe]

Have you considered mkdocs (https://github.com/mkdocs/mkdocs/)? It is a static site generator based on markdown. Right now I can't see how people will contribute if the documentation is maintained and hosted in yet another system. Creating a PR for the docs in GitHub is easy for most.

Pages like:

• https://www.mkdocs.org/
• https://docs.tandoor.dev/

look really good

There are a ton of plugins:
https://github.com/mkdocs/mkdocs/wiki/MkDocs-Plugins

[andersmelander]

Hmm. Have you looked at the source of those MkDocs sites? Spoiler; It's a hand edited mix of markdown and html.
So as far as I can see MkDocs is no better than the current solution. It requires manually editing a bunch of text files, running them through a builder and then upload the generated files to the doc site.
Updating the documentation using MkDocs would require:

1. Fork the documentation repo.
2. Install Python.
3. Fetch and install MkDocs.
4. Learn how MkDocs works.
5. Locate and edit the documentation files.
6. Build the static documentation.
7. Push the edited and generated files.
8. Create a PR.

Personally I wouldn't make it past step 2 before deciding that my time was better spent elsewhere.
No, I'm looking for something that makes it really easy to produce something nice, if only because otherwise I know I won't be using it (as witnessed by the current state of the documentation). Something like this:

• Editable online.
• WYSIWYG editing.
• Support for most basic layout elements such as tables, columns, boxes, etc.
• Menus.

I think most people probably access the Graphics32 documentation through the link on the GitHub project page. I certainly do because the files in Graphics32\Documentation are broken because someone forgot to push their changes when they updated the graphics32.github.io files. My point is that if people currently access the documentation by clicking on a link on a static page on graphics32.github.io, then that link could just as well send them somewhere else. I don't think they would care as long as they can easily access the help.

[luebbe]

I'm fine with anything. You must choose whatever you are comfortable to work with. I can only say from my perspective that I have contributed to projects that are using mkdocs and I found it easy from that perspective. I didn't have to set up mkdocs though. It was already up and running :)