Documentation

[videlanicolas]

While the tutorial in the README helps to get started with inkgd and setup a story, it does not explain the methods to use. Once must infer them from the code and test their way through to get the most out of Ink.

To solve this Inkgd must have a documentation that details the methods found in the API, this way the user can read the docs and understand what methods they should use. I propose we open an account in ReadTheDocs for Inkgd, and build the Sphinx documentation in a separate folder in this repo.

[ephread]

@videlanicolas great idea, thanks for spearheading this!

I created the project on ReadTheDocs and added you as a maintainer. How would you want to start this, do you plan to reuse the existing doc comments found in the C# code?

[videlanicolas]

I created the project on ReadTheDocs and added you as a maintainer.

Thanks!

do you plan to reuse the existing doc comments found in the C# code?

Yes, I think we should import the comments in the C# code from Ink unto this repo. The best practise would be to import the comment from the function in C# to the function in GDScript, that way if this project doesn't support a given function of Ink we can declare it in the function's comment.

We should also add a "Getting Started", "Tutorials" and "Troubleshooting". I don't own a Mac so I cannot do the steps to install Inkgd on Mac, but can do so in Windows and Linux/Debian. For the tutorials section, the example you have submitted will be perfect. The README file should be a TL;DR of this project plus a link to the documentation for more details.

I'll get a PR with the basic stuff to get the doc up and running, we can then tackle each section separately.

[videlanicolas]

With these two last PR we now have continuous builds on ReadTheDocs (https://inkgd.readthedocs.io/). I'll now work on getting the "Getting Started" section.

[videlanicolas]

Thinking how to do the Tutorial section. I'm thinking of a simple RPG-style game where a knight needs to save the prince/princess, the player moves the knight and interacts with other people to gather items and complete the quest. This way we can showcase how to gather text from a story, choices arrays, tags and variables.

I'll sketch something up and make it available in the AssetLib in Godot, that way we can share the example easily. The finished tutorial will contain an unfinished game, so that the user needs to complete the code in order to make it work.

[videlanicolas]

For the class documentation, we should add docstrings to each function in this repo's API, and auto-generate the documentation from those docstrings. Nothing too fancy, just a summary of the function/class plus a summary of what the inputs/outputs are.

Given that the functions are the same as those found in Ink's runtime engine we could build a tool that extracts docstrings from Ink's functions in C# and ports it to docstrings in GDScript, but that could prove a little bit too complex. Maybe the solution here is to build a tool that extracts Ink function's docstrings in C# into XML files in this repo under docs/source/classes/, but there may be functions/parameters in C# that wouldn't make sense to import in GDScript, so we might end up documenting stuff that this repo doesn't have.

@ephread how was the runtime of this engine built? Does it have the same classes as those found in Ink's runtime engine or are some classes modified in order to fit with GDScript?

[videlanicolas]

The troubleshooting section should be easy enough to do, a new file named docs/source/troubleshooting/index.rstcontaining common mistakes people do with Inkgd.

[ephread]

Thinking how to do the Tutorial section […]

Great idea!

---

Given that the functions are the same as those found in Ink's runtime engine we could build a tool that extracts docstrings from Ink's functions in C# and ports it to docstrings in GDScript, but that could prove a little bit too complex. Maybe the solution here is to build a tool that extracts Ink function's docstrings in C# into XML files in this repo under docs/source/classes/, but there may be functions/parameters in C# that wouldn't make sense to import in GDScript, so we might end up documenting stuff that this repo doesn't have.

Although it might be tedious, it's probably going to be faster by hand, due to name and syntax differences. A quick (and naive) search returned 123 individual "doc comments" for 0.9.0 (the version of the runtime inkgd is currently based on). Most of the code is somewhat internal and not exposed to the end-user.

If you're feeling adventurous, here's the XML doc generated by Visual Studio for the runtime assembly:
ink-engine-runtime.xml.zip

I can open a PR to track progress on the comment migration if you want. I'd list the files involved and they can be tackled by anyone willing to land a hand (that's what we're doing every time we need to port over the code from a new version of ink).

---

how was the runtime of this engine built? Does it have the same classes as those found in Ink's runtime engine or are some classes modified in order to fit with GDScript?

It was built, like inkjs, by a human transpiler. 😁

Since ink doesn't have a spec, it's really difficult to create a implementation of the runtime that is 100% compatible with inklecate without closely following the original C# source code. inkgd is basically a carbon copy of the C# source code, with changes made to accommodate GDScript's particularities. That's why inkgd's code is a bit weird and not always idiomatic. I had planed to document the specifics in CONTRIBUTING.md, but I never got around to do it.

---

The troubleshooting section should be easy enough to do, a new file named docs/source/troubleshooting/index.rstcontaining common mistakes people do with Inkgd.

Documenting caveats and common problems is a great idea! There's probably a bit of content that can be reused in past issues.

[videlanicolas]

Although it might be tedious, it's probably going to be faster by hand,

Sounds good, I'll take some time to do this.

I can open a PR to track progress on the comment migration if you want.

That's ok, I'll create a branch on my fork and do a commit tree for this, then file a PR.

It was built, like inkjs, by a human transpiler. 😁

My main worry here is that everytime Inklecate changes their documentation, we would have to do that manually. If there's something automatic, like a tool that Github can run periodically, that compares the comments of Inklecate with the comments on this repo, that'll maintain the documentation up to date without us interfering. But again, if the documentation changes then the code might change as well, so we might want to take a manual look at it. Fair enough, we can do this manually.

The game is almost done, I didn't had too much time to spend on it, I'm in the process of moving countries. Once I have time back at the end of the year I'll be able to submit it.

[ephread]

But again, if the documentation changes then the code might change as well, so we might want to take a manual look at it.

I port the changes from upstream on each new version anyway, so it could definitely be a small addition of that tedious process.

The game is almost done, I didn't had too much time to spend on it, I'm in the process of moving countries. Once I have time back at the end of the year I'll be able to submit it.

Awesome, there's going to be significant change to inkgd's interface in the future. It's going to use proper resources and the dock is going to be less confusing. I'll walk you through the changes once I'm done with them.

Good luck with the move!

[ephread]

@videlanicolas I got myself acquainted with Sphink & reStructuredText and massively reworked the documentation. Feedback welcome!

I split the introduction into multiple pages so that they are more readily available from the sidebar. The game tutorial will fit nicely after Initial Configuration. I've commented out mentions of it for now to prevent confusion, but we can restore the line once the next step of the tutorial is ready.

The API is currently completely written by hand, but I was thinking about using Godot's make_rst script and write the doc comments in an xml file unless you had something else in mind.

Also, I imported Godot's script to highlight GDScript code in the doc.

[videlanicolas]

got myself acquainted with Sphink & reStructuredText and massively reworked the documentation.

Nice! This is practically done already. I think this looks very good.

The API is currently completely written by hand, but I was thinking about using Godot's make_rst script and write the doc comments in an xml file unless you had something else in mind.

Yes, my idea was to have a script that reads the comments from the Ink C# API and converts them to an XML, then use make_rst.py to convert it to an .rst file. Doing a manual XML and then use the script from Godot looks good to me.