WIP: Improve look of documentation

lithekod / snake-ribs

A simple python code skeletons for making games.

MIT License

0 stars 2 forks source link

WIP: Improve look of documentation #17

Closed TheZoq2 closed 3 years ago

TheZoq2 commented 3 years ago

The documentation felt a bit too cluttered for me, so I changed it a bit. This is what it looks like rendered:

I'm not a huge fan of the colors on the doc headers either, but that might be more of a personal preference. In any case, i'll try to come up with an alternataive

TheZoq2 commented 3 years ago

A proposal for reducing the amount of color. To me, this draws the eyes towards the actual text rather than the header bars.

TheZoq2 commented 3 years ago

I should probably focus more on the docs content, but this is a lot more fun :)

Limited maximum width of content to avoid super long lines
TOC to a floating sidebar if there is enough space
Re-ordered documentation to put "What is RIBS" on top

Peek 2020-09-20 12-00

FredTheDino commented 3 years ago

Nice! Looks a lot easier to parse now! Nice PR.

TheZoq2 commented 3 years ago

One final thing, removed the argument list from the TOC to make that easier to parse :)

TheZoq2 commented 3 years ago

Hang on, something broke when I did something and now text is super small, going to look into it

TheZoq2 commented 3 years ago

Looks like html got confused by the <code> tags being present in the ids and names of elements. Eventually it had enough and just filled the whole document with them :) Should be fixed now

TheZoq2 commented 3 years ago

Never mind, still not fixed :scream:

TheZoq2 commented 3 years ago

Ok, fixed now (I think)

Making my own todo list:

[x] Some padding on the bottom of the ToC
[x] A slightly larger monospace font.
[x] Some way to differentiate code blocks from the other code, a different background or a border or something.
[x] Nicer looking links in the TOC
[ ] Maybe highlight default arguments and keyword arguments in the titles
[x] Darker code block background
[ ] Fix ugly spacing after description blocks

TheZoq2 commented 3 years ago

Moved the gray color to the code examples only. I think it's an improvement but I'm not sure

FredTheDino commented 3 years ago

I like it, makes them easier to parse! :+1:

sornas commented 3 years ago

I agree with having grey only for code but I think it can be a bit darker.

TheZoq2 commented 3 years ago

Updated table of contents to get rid of ugly visited link color, improve font size and add a hover effect.

I also added a bit more spacing between headers and content. Next i'll look into fixing the ugly spacing after some descriptions

TheZoq2 commented 3 years ago

Made some final adjustments. There might be one or two things left that I could do, but i'm happy with this for now

EMattfolk commented 3 years ago

I was thinking that the arguments should go right under function definitions, so as to get a quick overview of the function. I could do this if you guys think it's a good idea.

TheZoq2 commented 3 years ago

I think that makes sense

TheZoq2 commented 3 years ago

Rebased on master now, so this should be ready to merge

sornas commented 3 years ago

It looks like not everything got the larger monospace font.