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 »

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: 335
Joined: 02 Jan 2016, 02:51

Re: Scripting Reference

Post by Ravenwing »

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 »

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: 335
Joined: 02 Jan 2016, 02:51

Re: Scripting Reference

Post by Ravenwing »

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 »

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: 442
Joined: 22 Nov 2014, 10:51

Re: Scripting Reference

Post by sjek »

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. pit@

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
User avatar
sjek
Posts: 442
Joined: 22 Nov 2014, 10:51

Re: Scripting Reference

Post by sjek »

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.
User avatar
sjek
Posts: 442
Joined: 22 Nov 2014, 10:51

Re: Scripting Reference

Post by sjek »

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
User avatar
sjek
Posts: 442
Joined: 22 Nov 2014, 10:51

Re: Scripting Reference

Post by sjek »

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.
User avatar
sjek
Posts: 442
Joined: 22 Nov 2014, 10:51

Re: Scripting Reference

Post by sjek »

now that i'm in a scroll, just a question. (edit: as talking about documentation instead of a software)
could this be good licenced at CC BY SA NC as would that prohibit using this documentation for commercial purposes as is or would CC BY SA be better option ?

i figure that GhanBuriGhan purposebly chose the tutorial like approach for MSFD and for copyrights it says these
Special thanks go to GhanBuriGhan, who gave me permission to update his indispensable
guide. Also thanks to Dave Humphrey for his permission to use the information on UESP
wiki, and everyone who contributed to that wiki.
Disclaimer & Copyright Statment: The Elder Scrolls, Morrowind, Daggerfall, Arena, Tribunal, Bloodmoon the TES
Construction Set etc. are property of Bethesda Softworks, a ZeniMax Media company. The authors and editors of this manual
make no claims to these names and trademarks. In all other respects I (GhanBuriGhan) maintain the copyright for this
document. This guide is fully unofficial and in no way am I, any other authors or editors, or Bethesda responsible for any
damages or loss of data, patience, hair, or sanity inflicted through the use of this manual. You can freely distribute this
document as long as you keep it intact and unmodified.
apart from many thanks. i take that this scripting reference need to be done with help of a more current research.
can this still be used with citing the source thought and what licence would go with it ?
or something similar about granted permissions, thanks and copyright notice.


on the document: miscallenous portion propaply needs a bit restructuring to bypass big single list and
that said even uesp style wikipedia could be best option as reference.
it has all laid out in relatively small space and allows neat reference to other functions
same in phinx is possible, thought a bit tedious. maybe smaller font.
"interlining" the document with itself is better but is that really needed,
as maybe better for writing more complicated api's and such.
have to dive in some time again.
Post Reply