Update Docs

[frogfromlake]

Hey ! Thanks for this awesome mod man. Looks like you put a lot of work in it! I am struggling with the docs tho. It seems there are some wrong/deprecated examples and unclear or no descriptions. Can they get an update/revision? Let me know if i can help.

Cheers

[untoldwind]

Sure, every PR or error correction is much appreciated.

Most of the documentation is just markdown in https://github.com/untoldwind/KontrolSystem2/tree/master/docs (using Sphinx for rendering).

Though the reference section (https://github.com/untoldwind/KontrolSystem2/tree/master/docs/reference) is generate from the sources. E.g. https://github.com/untoldwind/KontrolSystem2/blob/e4d85f253f01c37f57afb1c3264071c61a60f6d1/KSP2Runtime/KSPVessel/KSPVesselModule.Vessel.cs#L72-L73 will be converted to https://github.com/untoldwind/KontrolSystem2/blob/e4d85f253f01c37f57afb1c3264071c61a60f6d1/docs/reference/ksp/vessel.md?plain=1#L1592

... and unluckily there are still a lot of methods and fields in the KSP2Runtime that are missing a proper description

[PhilouDS]

Sure, every PR or error correction is much appreciated.

If you're interested, I could try to make a tutorial as the one we can find in the kOS documentation : https://ksp-kos.github.io/KOS_DOC/tutorials/quickstart.html

In my youtube channel, I did some videos. There are not really tutorials but I try to explain some basics of KS2 as I understand it (as a neophyte): https://www.youtube.com/playlist?list=PLf_pkTl38qfjPK5rEI51BPqfUEF9yLPAw

[untoldwind]

Having some kind of step by step intro solving some common problems would be really nice. As it stands right now I would say that the learning curve is way too steep, especially without deep programming experiences.

In a way the scripts in the to2 folder were supposed to provide a set to of small tools to use and improve upon ... but they themselves are not all that well documented either.

[PhilouDS]

In a way the scripts in the to2 folder were supposed to provide a set to of small tools to use and improve upon ... but they themselves are not all that well documented either.

With my personal experience, I found the scripts provided too difficult to understand at the beginning. But I studied them and finally understood the logic of the language. Some scripts are difficult also because they use space mechanics. When you know the language, the provided scripts are great examples of the power of to2.

I keep in mind the step by step intro and start to think of contents that could help beginners.

[lefouvert]

IMHO, the most crippling misses are some key words and key feature definition. continue and break and return for exemple. Yes they are obvious, but never mentioned. Or the simple fact the last expression is automaticly returned. For an old's farts as me, it took me at least 20 minutes before figuring it. Some misses are also on operators ( Direction + Direction is a thing ;) ) Or the cliffhanger of the & operator on records. Wanna know what it do ? Go see Records doc's. Records doc : does somebody talk about &? Never heard about. (Ok, it's an easy one to gess, but sill)

Would happily participate (For the written part. I'm not at my ease on live)

Obvioulsy, the heavy part is a description for each parameters of each references. (While I'm thinking about, does vessel.momentum is able to give anything other that 0.0 ? Even with a vessel spining like a Beyblade, it give me a nice and stable 0.0...)

And The HARD part (at my eyes), space positioning explainations. Frames, direction, quaternions hidden behind, range of value (Yeah, direction give me pitch roll yaw 0-360 range... And vessel.manage_steering take ? pitch YAW roll ! And you know why you are spining as if you wanted to head off Jebedia ? Because manage_steering is 0-1 range and you give him a nice 92.73° ! A bit confusing first time without warning, but funny when understood :) )

TLDR : had fun to understand some things, but I think it's better to help to grow doc.

[frogfromlake]

Sure, every PR or error correction is much appreciated.

Most of the documentation is just markdown in https://github.com/untoldwind/KontrolSystem2/tree/master/docs (using Sphinx for rendering).

Though the reference section (https://github.com/untoldwind/KontrolSystem2/tree/master/docs/reference) is generate from the sources. E.g.

https://github.com/untoldwind/KontrolSystem2/blob/e4d85f253f01c37f57afb1c3264071c61a60f6d1/KSP2Runtime/KSPVessel/KSPVesselModule.Vessel.cs#L72-L73

will be converted to https://github.com/untoldwind/KontrolSystem2/blob/e4d85f253f01c37f57afb1c3264071c61a60f6d1/docs/reference/ksp/vessel.md?plain=1#L1592

... and unluckily there are still a lot of methods and fields in the KSP2Runtime that are missing a proper description

I just forked the repo and was checking it out.

I was thinking about if we/i could add a Example property to (e.g) the KSMethod Attribute to show an example of the usage of a method in the docs reference section for each method/field etc. I guess this would make it a lot easier for people who dont have a lot of coding knowledge. I was wondering how the docs are generated tho. I found a few places that might make sense but i am not sure how that stuff is rendered etc. if you would have a little example on how to implement that within your structure of rendering the docs reference and if you like that idea i could propably do that.

... and unluckily there are still a lot of methods and fields in the KSP2Runtime that are missing a proper description

Those descriptions are set in the [KSField(Description = "text")] fields, right? So that would just be a matter of diligence i guess which is also ok for me. ;)

[untoldwind]

The docs (at least the reference part of it) is generated by this program: https://github.com/untoldwind/KontrolSystem2/blob/master/Tools/GenDocs/Main.cs

Essentially it iterates through all the type-information and created markdown files from it.

Descriptions can be added to all KSMethod, KSFunction, KSClass and KSField. It is also possible to add descriptions to function/method parameter, e.g.: https://github.com/untoldwind/KontrolSystem2/blob/2b9e9d32462b28d4d3c9136eaee8c7bb5c55620e/KSP2Runtime/KSPOrbit/KSPOrbitModule.Body.cs#L74

As for examples ... technically the length of a description is not limited, there are already some multi-line examples like this: https://github.com/untoldwind/KontrolSystem2/blob/2b9e9d32462b28d4d3c9136eaee8c7bb5c55620e/KSP2Runtime/KSPOrbit/KSPOrbitModule.Orbit.cs#L69 ... but this might become somewhat cumbersome.

What I was thinking about (but never managed to do due to time-constraints) was adding something similar to the examples in golang (https://go.dev/blog/examples). Essentially you write some example code + the expected outcome and then just have something to add to the documentation and something to automatically test at the same time.

[github-actions[bot]]

This issue is stale because it has been open for 60 days with no activity.