Scripting Reference

All discussion on project related documentation including source docs, manuals, and tutorials go here.
Post Reply
desttinghim
Posts: 9
Joined: 19 Dec 2017, 00:00

Scripting Reference

Post by desttinghim » 07 Mar 2019, 17:39

I am interested in getting the scripting reference documentation made. (Gitlab Issue)

My eventual goal is to get it added into OpenMW-CS as offline documentation, but before that can happen it needs to be made. I am willing to work on this, but I am not sure where I would put the files and how I would format them. Any guidance on this would be appreciated.

User avatar
Ravenwing
Posts: 334
Joined: 02 Jan 2016, 02:51

Re: Scripting Reference

Post by Ravenwing » 07 Mar 2019, 18:55

All documentation should be in the Docs folder in the main repo. Please use the restructured text syntax and use Sphinx to build the docs locally. This is what RTD uses which will give you an accurate idea of how it will turn out. Both RST and Sphinx have pretty good documentation so I’d search there for specifics. Please also see our style guide on which is kept in the same location as the docs. I can help more when I get home tonight.

I do have a guide that I had been working on and never published so maybe that would be useful to you even in its unfinished state.

desttinghim
Posts: 9
Joined: 19 Dec 2017, 00:00

Re: Scripting Reference

Post by desttinghim » 08 Mar 2019, 04:30

Thank you for the reply: it helped a ton! It looks like sphinx is capable of producing QtHelp files! That should make integrating offline help much easier.

Yes, I would be interested in seeing the guide that you are working on.

User avatar
Ravenwing
Posts: 334
Joined: 02 Jan 2016, 02:51

Re: Scripting Reference

Post by Ravenwing » 08 Mar 2019, 06:57

So turns out we had merged an in progress version of the documentation contribution guide and I'd forgotten about it. Whoops!
https://openmw.readthedocs.io/en/master ... HowTo.html
I think you're already above the level this was meant for, but feel free to give it a look over to see it anything helps.

The resources I have bookmarked for documentation are as follows:
http://docutils.sourceforge.net/docs/us ... ckref.html
http://docutils.sourceforge.net/docs/re ... dtext.html
http://www.sphinx-doc.org/en/master/usa ... asics.html
http://www.sphinx-doc.org/en/master/usa ... index.html
https://github.com/edx/edx-platform/wik ... ll-Request
https://gitlab.com/gitlab-org/gitlab-ce ... d#markdown

Also recommend using the Read the Docs theme for Sphinx if you want to get the most accurate preview of your work. I think I'll post any other thoughts I have directly on your MR but feel free to keep asking here for any general docs questions for visibility!

desttinghim
Posts: 9
Joined: 19 Dec 2017, 00:00

Re: Scripting Reference

Post by desttinghim » 08 Mar 2019, 16:56

Thanks for the links! But you're right, I have already skimmed your documentation contribution guide and I don't really need the guidance :P

One thing I am wondering about is how we want the offline help to be added to the edited executable. I believe it would be possible to include it as part of the build step, but then building openmw-cs will require python and sphinx installed. Building it manually and including it by hand would also be possible, but that is error-prone and the offline help will likely get out of sync. Thoughts?

User avatar
sjek
Posts: 430
Joined: 22 Nov 2014, 10:51

Re: Scripting Reference

Post by sjek » 11 Mar 2019, 19:02

Seeing as the MR takes shape quite well sorry for jumping a bit further, but how have you considered to report the little deviations from vanilla engine? Is there gonna be different section for every command like in UESP wiki or wider take like in morrowind scripting for dummies 9 ?
Tougher question is where is the line of bug and feature, plankly speaking major point / hindrance, while making take on documentation. [email protected]

I will ladly help in reporting and testing but can't read the code myself, rather daily dosage of github activity.
As having good place to write the info down would be immensely helpfull.

Edit: Now thinking about it, i can theoretically help as is. Loosely bouncing around just bugs me.

Edit2: sphinx it is then :P
"life is crazy"
"craziness has beauty which only crazies understand" some movie clip in the head.
https://wiki.openmw.org/index.php?title=Testing

User avatar
sjek
Posts: 430
Joined: 22 Nov 2014, 10:51

Re: Scripting Reference

Post by sjek » 14 Mar 2019, 18:43

One thing I am wondering about is how we want the offline help to be added to the edited executable. I believe it would be possible to include it as part of the build step, but then building openmw-cs will require python and sphinx installed. Building it manually and including it by hand would also be possible, but that is error-prone and the offline help will likely get out of sync. Thoughts?
for the purpose of scripting reference, could it be included into web help instead, as basic help could be built for offline until we got something publication worthy.
https://openmw.readthedocs.io/en/master ... index.html

personally need to scrap that take on documentation as too wide in scope for now. First thing what would be needed is a list of every function like suggested in https://gitlab.com/OpenMW/openmw/issues/4090

---> those could include lists of made bugreports and commits, where found, before delving into vanilla scripting references. Testing vanilla engine is devilish with more complex scripts so that could be left for the last step without forgotting all the written reports.

would the web help be proper place for something like this or the wiki? editing here in forums with all the spoiler stags is a pain and mind maps stend to overgrowth quickly usually without good linking support. evernote is closest sane platform but not quite for me. zim notebook other one.

how scripting functions could be grouped?
UESP's categorical is kinda clunky as the function with gamemechanics differs and overlaps a little from how it's listed on the original help files i reckon. althought this is something to worry later after barebones are written.
"life is crazy"
"craziness has beauty which only crazies understand" some movie clip in the head.
https://wiki.openmw.org/index.php?title=Testing

User avatar
sjek
Posts: 430
Joined: 22 Nov 2014, 10:51

Re: Scripting Reference

Post by sjek » 24 Apr 2019, 08:48

https://scripts-workspace.readthedocs.io/en/latest/

This is shaping somewhat to it's final form. For adjusting to phinx folder structure the topics now have their individual subpages and "index" files therefore, to make moving around a bit easier. At the sources, conf.py have same extensions as the openmw. For other setting haven't dive into yet. There is for most cases large amount of functions on one page but all can be direct linked from putton on the side.

old: For cutting up the amount of files there's no possibility to direct link individual commands. On the other side there's only few commands per document to group them by functionality, so game mechanics can be explained on the start, end or in between.
It might be possible to get linking working by using ref tags instead of rubrik directive which hides the subtopic from content tree, refenting duplicates, but haven't figured out how yet.

https://github.com/sjek/scripts-workspace There's the source.
commit history is a mess but if you have sphinx installed, a "make html" command can be given in source folder.
_build contains the html files.

edit:
Handy CheatSheet, takes a while to sink in
http://openalea.gforge.inria.fr/doc/ope ... x.html#id3
"life is crazy"
"craziness has beauty which only crazies understand" some movie clip in the head.
https://wiki.openmw.org/index.php?title=Testing

User avatar
sjek
Posts: 430
Joined: 22 Nov 2014, 10:51

Re: Scripting Reference

Post by sjek » 23 Aug 2019, 13:51

There's only messagebox function topic line and same in some functions at stats unwritten and readme. Organizing has taken the last miles althought thats will life a bit as not a scripting wizard or coder. I have mostly time on weekends to work on this so might be slow to thinging this trought myself.

Open to remarks what could be improved before preparing all the files to needed structure and merging with master branch in own fork and making merge request. Or as this goes by to that fork merge. Putting new read the docs up as that comes xP

Naturally license is GPL which comes with openmw.
"life is crazy"
"craziness has beauty which only crazies understand" some movie clip in the head.
https://wiki.openmw.org/index.php?title=Testing

Post Reply