Godot-docs: Suggestion: Host auto-generated output of `doc_status.py` somewhere

[follower]

[TL;DR: Make it more obvious which class reference documentation still needs to be written by automatically posting output of doc_status.py on the web (via CI?).]

Background

As part of looking into improving the class reference documentation coverage I had been thinking of writing a script to highlight which class/method/etc docs still needed to be written.

Fortunately before going too far down this path I discovered this functionality already exists in the form of doc_status.py.

I think it would be helpful for the output of this script to be auto-generated and hosted/made accessible somewhere so that people can more easily see/find what still needs documentation.

Example current output (as gists)

1. Example Godot doc_status.py full output
2. Example Godot doc_status.py "only bad" output
3. Example Godot doc_status.py "only bad" output with doc links (see right-most column for link URL)
4. Example Godot (modified) doc_status.py "only bad" output with "0/0" and "OK" entries removed

Although it's helpful to have the table rendered via Markdown, due to GitHub's default width for gists in some ways it's easier to view in raw mode e.g. (4)

Possible extensions

I think having little graphical "progress bars" as an option could be helpful for getting a general overview.

Prior work

It seems 3 years ago there was a "Fill in the blank in the class reference" blog post which mentions the doc_status.py script and directs people to a "collaborative pad" (was here but moved to "Let’s Collaborate on the Godot Class Reference").

The collaboration page incorporated a table with output from doc_status.py but the most recent version referenced is "Status as of: 2017-12-09 (master)". (I'm guessing the output was manually pasted into the page by @NathanLovato who is listed as the owner of the page and I think coordinated a "sprint"/event around it.)

Hacky patch

Here's the hacky patch (which makes the output easier to skim) for (4) which could be incorporated into a new or existing command line switch:

diff --git a/doc/tools/doc_status.py b/doc/tools/doc_status.py
index 974ac2d05..2c176d5ba 100644
--- a/doc/tools/doc_status.py
+++ b/doc/tools/doc_status.py
@@ -152,7 +152,7 @@ class ClassStatusProgress:
         percent = int(round(100 * ratio))
         s = format.format(has=str(self.described), total=str(self.total), percent=str(percent))
         if self.described >= self.total:
-            s = color('part_good', s)
+            s = "" #color('part_good', s)
         elif self.described >= self.total / 4 * 3:
             s = color('part_mostly_good', s)
         elif self.described > 0:
@@ -208,7 +208,7 @@ class ClassStatus:
         output = {}
         output['name'] = color('name', self.name)

-        ok_string = color('part_good', 'OK')
+        ok_string = "" # color('part_good', 'OK')
         missing_string = color('part_big_problem', 'MISSING')

         output['brief_description'] = ok_string if self.has_brief_description else missing_string

[Calinou]

I like the idea :slightly_smiling_face:

I might start working on it as a proof of concept.

[Calinou]

I just finished a proof of concept: https://godot-doc-status.github.io/

The source code is available here.

I suppose this could be moved to the Godot organization if we want to make this official.

[follower]

Cool! Thanks for getting this going. :)

[Calinou]

@akien-mga Do you think we should make godot-doc-status part of the @godotengine organization? I can set up a redirect for the existing URL if needed.

[akien-mga]

Yeah that would be good. As @godotengine org member you might be able to transfer it yourself. GitHub sets the redirect automatically.

[Calinou]

Done: https://godotengine.github.io/doc-status/

Please post issues about that page here if you find any.