Defining roadmap to a feature complete web documentation

[AlanDrake]

We should define actionable tasks for reaching the point where we can say the web documentation is good and complete. And for that there are a few decisions to make:

1. Sidebar: I would like to have the main topics displayed there for ease of navigation, like the CHM. Is this possible to achieve? It's fine even having a javascript array of topic-titles somewhere, that I can parse to build it.
2. Index and interface: keep how it's currently implemented, as separate page, or make something else? It wouldn't be hard to make something like the chm, where you can filter the results. It would also be helpful if I have access of it as an array, so I can match things like Character.Say exactly and offer it as a search result that positions the user at the correct anchor.
3. Web vs CHM: Replace the CHM with a web version? I can find ways to make it fully work locally as a SPA without a webserver, but that will require having all the contents embedded either in the HTML or a javascript. Or, we could ship one of those third party micro webservers and serve it on localhost:somenumber. It's also possible to render markdown on the fly straight from javascript, or even build search indexes locally and saving them on localstorage and then checking against build number to regenerate them.
4. Mobile: hamburger menu and stuff. But does anyone unironically use the docs on a phone?

I'd say only 1&2 should be considered for the short term. I would like to at least have the genindex content on a javascript array, so I can load the page with the correct anchor.

Related issues:

• 122

• 130

• 101

[ericoporto]

4) I use the docs on a phone. It's the primary way I read stuff, even with the computer on. I even have a epub version I made for myself to read on a Kindle... In the reader I use on the phone (moon reader), it has a nice bar below which has icons for menu options including the "chapters", which are the headers. It's also how I revise text usually.

About SPA, I really feel static pages are better, they get better indexed on Google and other search engines, and they usually work with any browser. The fact SPAs work offline is nice - I have not seen evidence people actually install them though.

About the chm, if we want to replace it, the new build possibly won't be that different html wise, as it would need to function in a limited html capacity - we probably don't want to throw a huge browser along with the AGS Editor to run the docs, and there isn't a huge offer of HTML reading C# projects or embeddable Web Views. It would be more about getting a good indexing system and then making the ui in C#.

(On the topic of index, I have built some offline tools on this in the past, but using R, which has some really cool libraries on the topic, they can go through GBs of text do may be overkill for us. Shopping around I found an interesting indexing system using C#, lucenenet)

• see also: https://squidfunk.github.io/mkdocs-material/blog/2021/09/13/search-better-faster-smaller/#whats-next

Lastly, about the Sidebar, I think we need to manually maintain it, with only a script to check there's exactly one link for every document, reporting missing and duplicates. There's anything that differentiates a "see also" link from any other link currently, so there's no way to grasp a tree structure from just looking into the files.

[AlanDrake]

But you're using an app, so any web improvement is probably useless for you! 😛

About SPA/CHM We can have both static and spa (not the installable kind), it's just that if we use the file:// protocol we must only use only one page,or the localstorage will be different for evey single document. Issue that would be solved with a micro-webserver like php or python's, or anything else that can serve files through the http protocol, if we want to keep it offline.

Running from the http: protocol also has the advantage that I can async load other pages content via ajax and pretend the url has changed without actually leaving the page. Without http I can still use the # to fake page navigation, but I won't be able to make ajax calls, which sadly means I need a javascript way to have the contents. There are many options and hybrid approaches to make one's head spin. In the end, it's all about the end result we want to achieve.

[morganwillcock]

In my mind there are two separate parts to the manual:

• the script API documentation
• the part of the manual that describes the concepts and general usage of the programs

Something like a printed manual or public website would likely incorporate both of those parts, and that is also where the indexing becomes more complicated. The script API is potentially much easier to index if it acts purely as a lookup of a symbol, potentially just an index entry that points to the function signature and a brief description of what it does (perhaps with a short example). Technically, if required, this could also be synced to docstrings in the source code to make sure that everything is actually documented and stays in sync with branches.

The other part of the manual is more like a book, so that needs something that reads in a more structure way, but equally someone may be interested in how to do X, where the ideas, concepts, and examples surrounding X need to be somehow located, probably across multiple pages.

I don't think anyone is using the CHM viewer because that is their preferred way to read the tutorial, more likely they would prefer that in a browser or exported as a PDF. I think what it provides is the fast API index lookup from the current script editor and the special focus rules for its window (which allows it to co-exist more nicely with windows of the application which invoked it). To replace the CHM viewer I think whatever replaces it should target editor support, and I'm suggesting any editor, not the Editor.

It probably isn't a good idea to get hung up on the tooling before we know what the goal is. To suggest some ideas, how about trying to create the following two components:

1. Generic editor support tool

   Along with the general move of the build functionality from the Editor and into external tools, that should also include generic editor support. The tooling should allow the look-up of API documentation to be made by an editor and then returned back to the editor. This acts as a true replacement for the CHM viewer because the editor is responsible for displaying the content and that can cover cases where window focus needs to be handled differently. This should remove the main argument for moving away from the CHM viewer because the new viewer has the context and ability to provide "fixes" to complaints.

   Maybe this falls within or alongside something like an LSP server, maybe it has to be entirely separate, but effectively this is some sort of symbol lookup and a return of some kind of structured data. Maybe something like an HTML page would be an optional return type, but the focus is on the data not the presentation. I think more likely you would return the content itself as text (String.Format function signature), with optional links ("read more about formatting strings"), which an editor can treat as something like a tooltip. If it is the world's worst LSP server that just returns the docstrings for the current context, that would do as a start.

2. Public website

   This is essentially the AGS book. The contents of the site are structured in a way that works as both an introductory guide and a reference, the script API reference is present but listed separately.

   The contents page of the site describes chapters which introduce ideas and concepts, the relevant keywords that relate to content and concepts are listed in the general index. The key thing here is that the script API index is separate, and just lists all functions and objects. The script API index entries point to the "docstring" reference for that symbol, with additional entries for where the same symbol is explicitly mentioned anywhere in the manual.

   I'll also suggest it should be printable and equally usable in its printable form, to literally function as book, on paper or electronically with a document viewer.

Potentially there is substantial cross-over in how both of these are built and function, I imagine there would be multiple options for bundling the equivalent of the website with editor tooling and searching it, but does the above sound feasible as a way to replace the CHM viewer and have a better web-based manual (potentially resolving all three of the related issues linked in this ticket)?