Openra: Traits Documentation too long

[CH4Code]

Hi, recently the wiki on Traits has been showing this

probably because there is so much awesome content in OpenRA even the Wiki cant handle it!

In an attempt to dirty-fix this (delete from bottom to at least show some of the traits) I might have broken the edit button somehow o.O ooops.

[GraionDilach]

This will be really problematic, considering that we've already added a bunch of traits since last release. Can't we split the Traits page based on namespaces?

[pchote]

Thanks for reminding us of this. We should fix this for the second playtest alongside the planned upgrade rules overhaul.

[pchote]

https://github.com/OpenRA/OpenRA/wiki/Traits-%28playtest%29 looks fine to me, so removing from the milestone. If it breaks again we can win some headroom by removing the giant table of contents from the start.

[pchote]

IMO the long term fix for both this and the Lua API should be to change the utility rule to output json instead of markdown. An externally managed project can then present a web interface with a version selector (to change the json source) and a filter field that can be used to quickly narrow down the results to whatever is wanted.

[GraionDilach]

It became really dependant on GitHub's server usage at the moment, and i feel it breaks more often than not these days.

[ghost]

IMO the long term fix for both this and the Lua API should be to change the utility rule to output json instead of markdown. An externally managed project can then present a web interface with a version selector (to change the json source) and a filter field that can be used to quickly narrow down the results to whatever is wanted.

As in intermediate solution, we could use the generated markdown files in an external project and make them more accessible. I have an example of how it could look like set up here. The software used can be configured to work like a PWA which means that pages you visited earlier in a session are still available offline.

Required changes here would include minor modifications in the formatting of generated files and adjustments to push the generated files to the external project on commit / tag (which itself would build the output on commit).

While at it, I'd do the same for the lua and weapons documentation. If the external project would get approved by OpenRA members, I'd like to transfer its ownership to the OpenRA organization in similar fashion like we did with OpenRA/openrauseraccounts.

[ghost]

It would still be very useful for other projects that interact with the trait/lua data (for example an online tool to create rules) to let the utility output json instead of markdown.

[ghost]

I have a prototype of the ExtractDocsCommand that uses the Newtonsoft.Json dependency to optionally output JSON instead of markdown. It can also optionally write each trait data-object in markdown or json to a file named after the trait.

An externally managed project can then present a web interface with a version selector (to change the json source) and a filter field that can be used to quickly narrow down the results to whatever is wanted.

I don't know which other fields besides the trait name would be worth filtering. The only advantage I see would be that all versions would be available at one page. Currently each version has its own page. Using markdown has the advantage that the generated html page is with the used theme offline available after loaded in the browser. Unless I get feedback or guidance how to proceed, I'll do the following:

• have a page generated from a markdown document with all traits like now and a filter field in the table of contents, where trait names are listed to find and jump to the desired section
• have a page generated from a markdown document for each trait linked from the section with additional git log information, showing the last N changes with a link to the commit on github
• rework the search function to show seach results in tabs for the different versions

[ghost]

I'm getting the feeling that the mkdocs theme I'm using is not the right thing for us. I like it but it has a ton of node dependencies and we have nobody that is used to work with node and webpack and I am concerned that I will be the only one being able to work with it. And my edits are really ugly and bad hacks that likely conflict with any updates upstream. It would have been fine to use the distributed theme but I think we are not able to maintain a customized fork.

[Wilmatron]

Hi all, It appears the Traits wiki page is problematic again as I'm getting "the wiki page took too long to render. This wiki page’s content is too large to render on this page". Just making you aware. Cheers.

[Mailaender]

Use https://openhv.readthedocs.io/ in the meantime.

[Mailaender]

Ping @Rekojeht who currently blocks the proper OpenRA subdomain.

[Rekojeht]

I’ve updated the ReadTheDocs to point to the proper GitHub repo. Let me know of any questions or issues! :)

On Jan 19, 2020, at 12:21 PM, Matthias Mailänder [e-mail] wrote:


Ping @Rekojeht who currently blocks the proper OpenRA subdomain.

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub, or unsubscribe.

[abcdefg30]

https://openra.readthedocs.io/en/latest/# still seems to point towards .rst files that no longer exist in the repository.

[Mailaender]

Try setting it to https://www.mkdocs.org/ (MarkDown)

[Mailaender]

and maybe add some OpenRA members to the team.

[pchote]

and maybe add some OpenRA members to the team.

It should be basic common security sense to not host any official project services on servers/services that aren't exclusively controlled by the core team.

[Mailaender]

Also https://github.com/OpenRA/docs/blob/master/api/release/traits.md etc. now exists which is also rendered and does not seem to suffer from the wiki timeouts.

[Mailaender]

We have set up https://docs.openra.net/ now for quite some time.