NET-BYU / sss

11 stars 1 forks source link

Page "API/Display" - Code documentation drawing poorly #34

Closed doglman closed 1 year ago

doglman commented 1 year ago

I'm going to use the function draw_text() as an example, but this issue appears across the entire page.

The code documentation renders in-line without any formatting. This means that even though the comment documentation has each function parameter in a separate line, the github-pages renderer is smashing all those into one paragraph. This makes it difficult to determine which parameter the explanation text is referring to, and is generally difficult to read.

Suggestion: Adjust the documentation so it renders more nicely on the page. This will require some experimentation to figure out the details of the renderer. It's possible we just need to insert additional blank lines in between each parameter description so they are each broken into their own paragraph. Other possible solutions could include using a Markdown bulleted list or HTML <br> tags.

christopolise commented 1 year ago

Thanks for bringing this one to light. We really need to recomment all of the code and format the rest of it so that it is compatible with mkdocstring. I went ahead and fixed this in 1ae6fb0 but I have opened up a new issue #39 so that we can tackle this a little more intentionally.