Upbge: Proposal: Rework and join GE manual and API

[joelgomes1994]

Hello! First, let me explain my proposal...

• BGE's official manual is quite incomplete, and probably will be removed/totally reworked with the release of the Interactive Mode.
• Is it a good idea to keep Blender manual and GE manual together, but not a good idea to keep GE manual and GE API together? See an example of both GE manual and API on the same docs. My proposal is to make docs only for GE, manual and API on the same website, without Blender manual or API along with it.
  _Note: I understand that Blender API is automatically generated, but GE is not, so I defend a new format of GE only API, along with GE manual._
• UPBGE has a lot of new features documented only on release notes, but listing them on a documentation is crucial. Furthermore, UPBGE having its own docs is absolutelly beneficial for various other reasons.
• Docs can have direct references from/to related subjects on the same manual (example: Action Actuator page on manual can reference to BL_ActionActuator page on API, and vice-versa).
• Freedom to the UPBGE community on improving the manual with the new format (example: add advanced explanations about subjects, as in Tutorials For Blender 3D).

I do use Sphinx to create docs, and I can take this task of reworking and moving all the current documentation to a new repository, totally under control of the UPBGE team. My idea is the same format of Godot Engine's docs, as in the example above.
I can start it right over an acknowledgement about the idea. What the UPBGE team thinks about it?

Thanks. :smile:

[lordloki]

I'm with you. UPBGE documentation has to be improved. I will do a little plan to update documentation.

I think that we need to evolve from a "bge fork" to "a game engine integrated in blender". We need to be more independent but for this we need the aid from community.

P.D. we can take things or maybe even fusion with https://github.com/mikepan/GameEngineBook

[joelgomes1994]

@lordloki It would be great to mix both, if the authors agree, of course.
Take a look in the demo manual I've made and hosted on ReadTheDocs, it mixes both Blender manual (only Game Engine section) and UPBGE's Python API reference. With some tweaks, new organization and adding new content (as you suggested on GameEngineBook) it could be an amazing source of knowledge.
My source repository: https://github.com/joelgomes1994/UPBGE-Docs

[panzergame]

I agree to this idea.

Also i think it's a good idea to let the blender documentation aside.

[youle31]

Hi, I always used tutorials for blender website. I don't know if @lordloki or mikepan or "contributors to bge since a long time" are in relation with tutorialsforblender guys, but it might be interesting to contact them to see if they's be interested to create a similar website with upbge API changements. Or if it would be possible to "fork" their website and update it with upbge API (I'm not very motivated personnally, I just submit this idea).

Also, this would be cool to contact Mikepan (I think he is both an artist and a coder and I saw he was still involved in Blender as he shared a nice test scene for eevee). I think it was him too who wrote the nice mouselook used in water demo from martinsh :) Then it could be an idea to discuss this topic with him too (and dfelinto by the way maybe).

There was also lordloki idea to share a folder on the net with many example files.

Finally, there is the question of video tutorials (I created a youtube channel for upbge but there are only 4/5 videos...). It might be better to involve community to do the video tutorials and find a system to "tag" the best tutorials.

[joelgomes1994]

@youle31 Yes, I just sent an email to the Tutorials For Blender 3D guy (Clark Thames), I'll wait his answer.

The idea is to compile all the relevant info from all the suggested sources and make a concise manual, aimed for UPBGE, and keep everything on the same website, if possible. It seems to be a complex task, so planning the docs structure first will be needed. I'm not sure if @lordloki already suggested it, if so, could you make this planning? Indexes, that kind of stuff.

About the folder with example files, the Tutorials For Blender 3D example could be used, with most of the manual and API definitions followed by an example file link, instead of a folder full of example files with no clue about them.

And what about the docs source repository? Someone can fork/reupload my recently created docs repository to UPBGE user, and UPBGE adds me as a member to allow contributing to the repository, if possible.

[youle31]

@joelgomes1994 : hi, I think only @panzergame (the github repo owner) can add collaborators (give commit rights)

[joelgomes1994]

I'm slowly updating the docs at my repository, reworking the structure of files, correcting links and other stuff. I just added the standalone modules that can be used in GE as well (aud, bgl, blf, etc), along with bge API. Take a look on how it looks right now.. Definitely, the sidebar of Read The Docs theme suits the docs amazingly (specially the APIs).

I'll wait for the official repository creation.

[lordloki]

@joelgomes1994 I will create this night. Sorry for the delay.

[panzergame]

@joelgomes1994 : Great work !
About the source organization we could keep the whole documentation separately as you made or include it in the main repository, is just that i don't know what is the best for you to handle API update as i would like that any commit modifying the API includes its documentation changes too, to not forget updating the doc.

[joelgomes1994]

@panzergame
As it includes the manual, I think it's best to keep the things separated, to:

• Avoid mixing commits of docs and Blender source code;
• Allow having doc-related issues only;

Although the automatic API generation will not be available, as long the changes be written to release notes and API changes, everything should be fine.

[lordloki]

It is much better to keep the documentation repository separated from upbge sources. This way we can give commit rights to people without much risk.

[panzergame]

I was just worrying about the API dummy documentation, is it acceptable to manage for patches a pull request for the code and an other for the API doc ?

[youle31]

Hi, I guess it could be possible to create a fork of upbge for documentation and add many contributors, then import commits from this for with remote (git remote add doc, git remote update, git merge doc/master) system to mix flexibility/control.

[lordloki]

We can manage the code pull request as now and give commit rights for UPBGE-DOCs repository to the coder for documentation changes.

This way worked very well at beginning when blender was open sourced

[joelgomes1994]

As the repository has been created here, I will close this issue, as every documentation issue should be opened there now. Thanks. :smile: