Add an EditorSettings reference

[vnen]

The Project Settings is quite extensive. Having a reference page explaining briefly what each options does would be quite helpful. The same applies to the Editor Settings.

Bugsquad edit: ProjectSettings now has a reference, but it still has to be added for EditorSettings.

[NathanLovato]

Absolutely. At the same time, they might benefit from some reviewed grouping/reorganization first. In any case, a quick rundown of the most important settings would be helpful, to get started.

[akien-mga]

I agree with Nathan, we need to review the list and do necessary renamings/groupings before the 3.0 release (as it will break the support of previous settings).

[pwab]

I listed the entries of these two settings dialogs in two seperate gists for myself. Maybe it is helpful here too:
Project Settings: https://gist.github.com/pwab/6ff702daefbc3aab20d673d823e1778d
Editor Settings: https://gist.github.com/pwab/08fae71b19a6118c68eddcaed4dd038f

Some points came to my mind, while doing so:

• The Project Settings uses snake_case (with underscores) and the Editor Settings are written in CamelCase (with whitespaces). This should be unified.
• The only settings-section which uses categories is the Blackberry-section in the Editor Settings. This should be utilised more often. (for example in the Text Editor-section)
• The Settings-Dialogs aren't real windows so it is not possible to resize them, switch them in taskbar/with Alt+Tab or move them to a second monitor. It would be quite comfortable while changing settings, because changes are instantly applied (i.e. Editor colors). I'm sure there must be an issue for that, but I couldn't find one - sorry if I missed it.
• An explanation of each setting entry could be shown at the bottom of the settings dialog (like the description in the new node dialog)

[NathanLovato]

@pwab Do you still have the files? The gists aren't available anymore. Also, did you write some script to get the list from the source or what-not? That'd be useful because they're bound to evolve over time. I'm sure we can find contributors interested in working on this reference.

[pwab]

Yeah @NathanLovato I still have the files. I tried to rework the lists into a rst-table structure and started updating the items. But it wasn't ready yet (I'm not sure if I ever touched the v3-project-settings again) so be aware that the content of these files isn't up to date.

You can find the gists here (uploaded them again):

• godot_2_editor_settings
• godot_2_project_settings
• godot_3_editor_settings
• godot_3_project_settings

My workflow was just plain copying from the menu. I wanted to create a little helper script but wasn't able to understand how these entries are implemented in code. Maybe I looked into the wrong files and the menu item strings could be find with very easily. Then python and some little regex magic should do the trick.

[ZX-WT]

Should we just include the list or should we put a screenshot of that section of the settings above the list?

[DevinPentecost]

Hi,

I'm interested in filling out these descriptions as I run into them.
How should we go about adding them? I'm not sure the best way to do so. Since all we have are the gists provided above I don't know of a good place to input them.

Thanks for your help.

[NathanLovato]

Hey @DevinPentecost, thanks for the help! For now we should have a dedicated page in this repository, probably in learning/editor.

[DevinPentecost]

Hi,

Is the doc generated from the main codebase at all or is it all separately defined? If it's separate, that would mean that if a settings is modified or added, the docs would also need to be updated to reflect correct?

I can try to add the template from the gist above and create a pull request with a few of them filled out if that will help.

Thanks.

[NathanLovato]

There's no editor reference generated from the sources, and no tooltips for the editor settings in the editor. It'd be ideal if we could add this, as a lot of options are not self-explanatory and their order may change in the future.

But in the meantime, it's possible to write a reference by hand, have it in the learning section (again, maintained by hand, not generated from the sources) that someone could later reuse in the source code I guess.

[pwab]

As #962 and #965 seem to be on hold I started creating a script to extract the available information from godot itself. The script can be run in terminal is an EditorScript and creates two files almost ready for the docs pages.

I am not sure why the EditorSettings aren't working like the ProjectSettings. The interface should be the same (get_property_list()) but I do not receive the settings dictionaries.

EDIT:
The EditorSettings are working now. Thanks to #1109 I was lead to the right direction of retrieving the EditorSettings through the EditorInterface with the help of the EditorScript class. I'm getting a lot of entries about Recent Scenes with paths to very old projects of mine now. Will investigate this further if I find the time.

It would be great if the hint_string (or another variable like description or something like that) would contain a brief description about the effect of the setting. Then these overview pages could be extracted by the script on a regular basis (like the class files).

The script and the generated files can be found here:
https://gist.github.com/pwab/3e6586581bc38a9af6f6eeee96a04590

EDIT2:
The script is now almost "feature complete". I'm not sure if each settings entry should get a h3 (title = h1, category = h2) or if it should be made bold or something. (I only wanted to get rid of tables because they are not quite handy on mobile. But this can be discussed and if whished I can implement the table generation.)

The only thing I didn't get working for now is sorting of the second category-level.

[pwab]

I completed the script and did a successful build with the rtd theme. Results preview can be seen here:

Editor Settings

Project Settings

I would like to get some feedback on these points:

• Is the approach on generating these files from script (like the classes docs) feasible? Would it be possible to include descriptive information into the ProjectSettings- and
  EditorSettings-Propertylist that could be embeded like the rest of the information (name, hint_string)? Keep in mind that this would lead to the point where the contributers would have to edit these descriptions in the godot repository. But then these description-strings could be displayed as tooltip as well. (@akien-mga)
• Where to put these files in the docs structure? I placed them next to the keybindings because this seemed natural to me. (@NathanLovato, @cbscribe)
• What about the structuring of the page? Should the heading levels be adapted? Or should we use tables instead? (@NathanLovato, @cbscribe)
• What else could be improved? Any suggestions?

[Dar13]

Weighing in on this, I like the script-based approach because it incentivizes coupling the documentation and the implementations. When I was digging into the editor settings, it was strange to see the tooltips be the field names rather than something more useful, it would be a good quality-of-life change to add to both the editor and the documentation.

The structuring looks good to me, it separates the settings cleanly while grouping them as they are in the settings dialogs. However, it does differ from the class reference in that you didn't put the fields within each grouping into bullet points with descriptions underneath them. I'm not sure how much consistency within the docs are desired. Using italics for the descriptive text feels odd as well.

I do think that certain features will require further explanation (such as in #1164 for the external editor settings), but those could go into a separate section as you propose in that PR.

[DevinPentecost]

Hi, I agree 100% that the descriptions should be tied to the fields themselves. Requiring that contributers maintain two different areas when adding or improving these settings is just begging for them to fall out of sync. It is easy to justify forgetting to update them if they are not directly adjacent in the codebase. Additionally, pull requests can easily check the field descriptions to ensure they are not going stale. Having a separate document generated is great for when you are looking into the API. However, hovering over items in the UI and simply getting their name is very frustrating. Having at least a hyperlink to the documentation will help, but actual tooltips would be the best. By tying documentation with the fields, this allows them to be coupled together for viewing in the actual GUI. As far as the script so far, it's a great start but until we get actual descriptions I can't give too much feedback :) Thanks, Devin On Feb 19, 2018 16:05, "Neil Moore" <notifications@github.com> wrote: Weighing in on this, I like the script-based approach because it incentivizes coupling the documentation and the implementations. When I was digging into the editor settings, it was strange to see the tooltips be the field names rather than something more useful, it would be a good quality-of-life change to add to both the editor and the documentation. The structuring looks good to me, it separates the settings cleanly while grouping them as they are in the settings dialogs. However, it does differ from the class reference in that you didn't put the fields within each grouping into bullet points with descriptions underneath them. I'm not sure how much consistency within the docs are desired. Using italics for the descriptive text feels odd as well. I do think that certain features will require further explanation (such as in #1164 <#1164> for the external editor settings), but those could go into a separate section as you propose in that PR. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#395 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AA3olJlsCHqzKvVEK7I-hlg2663tCnUKks5tWgwygaJpZM4N9hxS> .

[NathanLovato]

@pwab Thanks very much for your work!

1. Putting them in the Editor Manual section is a good idea, that's where they belong
2. I think you can do something similar to how the reference displays member variables. Tables could be nice but they'd need some new css, right now the layout tends to break depending on the length of the description. Test example below
3. Best get in touch with Juan and the others on the IRC. The source data should probably live in the Godot repository and be reused in the editor for tooltips. Project settings support tooltips like any property but right now they're empty.

Suggestion for display, using level 2 titles for foldable sections, level 3 for setting pages, and bullet-lists for individual properties.

Application

Config

• String Name - The Project's name. The game window displays it in its title bar.
• bool Use Custom User Dir - If true, the res://user directory's name will be the one defined in the Custom User Dir Name property.
• ...

[pwab]

Thanks guys for the great feedback!
Won't have much time the next days but will soon create a PR where we can discuss the file structure further. I would like to get the pages into the docs first before proposing a PR with the corresponding script to the godot main repo. Should make it easier to discuss the idea behind it.

I'll keep you updated 🙂

[pwab]

Hey guys I found some time and updated my gist again. I refactored a bit of the code, added more styling options and made it a bit clearer I think.

I also went with the proposal of @NathanLovato. Now the properties are packed into much more condensed bullet lists. Adding type hints (like String, bool and so on) shouldn't be that hard if the property_list contains this kind of information. And in the end the hint_string could contain a description as well as the possible values to choose from (for now it only contains the latter).

[ZX-WT]

How is this going? With more users using godot and more options in the editor settings, we should add this to the doc for reference. Could there be a thing that people can fill in?

[pwab]

Thanks for reminding me, @ZX-WT. I'm going to set up a first PR during this next week soon 😅.

[pwab]

I tinkered with Godot 3.1 alpha today and saw this:

And the ProjectSettings class is already well documented. This leads to an easy translatable settings reference. Awesome! 👍

I hope that the EditorSettings will receive the same treatment (the latest docs page does not list the member variables yet).

[neikeq]

The special case for listing properties in ProjectSettings.xml is here:

https://github.com/godotengine/godot/blob/42ce497e7917e2bbea7c71b82d04837cc23a7396/editor/doc/doc_data.cpp#L236-L238

I tried adding a similar condition for EditorSettings, but the editor is not initialized when running --doctool so EditorSettings::get_singleton() returns NULL.

Any idea how we could do this?

[bojidar-bg]

On IRC there was a discussion about collecting all GLOBAL_DEF-s and EDITOR_DEF-s similar to how TTR calls are collected at build time. That way, all project and editor settings would be listed without having to rely on build settings.

[EricEzaM]

RE: Auto-generating the reference for the editor. Not easy. Also, some project settings are not included in the documentation due to issues discussed here (among other things) : godotengine/godot-proposals#1339 (comment)