List of small doc problems

[cspotcode]

A dumping ground for small problems I discover on the website and do not want to create a separate issue.

Formatted as a checklist so that Github shows the "create issue" button and we can spin these into issues if needed.

• "install from source" links to master branch, should link to development branch
  https://api.arcade.academy/en/development/programming_guide/install/source.html
• Sprite guide has broken sidebar due to wrong header levels
• arcade.color and arcade.csscolor api pages are incomplete, repetitive
  Fix their rendering
  Combine them into one, they repeat the same boilerplate. Should see all colors on one page
  https://api.arcade.academy/en/development/api_docs/arcade.csscolor.html
  https://api.arcade.academy/en/development/api_docs/arcade.color.html
• "Release checklist" is out-of-date
  https://api.arcade.academy/en/development/programming_guide/release_checklist.html
• "directory structure" page missing directory separators
  https://api.arcade.academy/en/development/programming_guide/directory_structure.html
• collapse API controller and and joystick pages into one, drop "Support" suffixes
• TOC render bug on ShaderToy Particles tutorial
  https://api.arcade.academy/en/development/tutorials/shader_toy_particles/index.html
• sidebar should auto-scroll to reveal current page
  way too easy to lose context when the scrollbar constantly resets to top

[cspotcode]

For "sidebar should auto-scroll to reveal current page" these snippets might work, though I didn't realize we have jQuery when I wrote them.

When link is clicked, save the position of clicked item into localStorage

document.querySelectorAll('.sidebar-scroll .current')[0].getBoundingClientRect().y

When page loads, compare position of current item to desired position from localStorage
offset scrollTop accordingly

document.querySelector('.sidebar-scroll').scrollTop = newValue

[sabadam32]

@cspotcode what is the issue with Sprite guide has broken sidebar due to wrong header levels?
The toctree lists sprite advanced and spritelist at the same level. How should this look?

[cspotcode]

@pushfoo is the best person to ask these days, but I think the issue was that the sidebar should be one-to-one link to page, but the first 3 sidebar links link to the same page. This might confuse the viewer, so they don't think the last link is worth clicking. But the last link is to another page, so the reader would miss out.

tl;dr it's inconsistent

[cspotcode]

Also, it's visually inconsistent. In this screenshot, I clicked on "Drawing with Sprites and Spritelists" but the sidebar highlights "What's a sprite?"

[pushfoo]

How should this look?

I've thought about this recently. One fix could be:

1. Move advanced techniques into their own top-level heading separate sprites
2. Expand the advanced SpriteList draw order section by mentioning the GPU-based depth support

Also, it's visually inconsistent.

Thank you for reminding me of this. I'll go through the issue again to see if there were notes on fixing this. If I remember correctly, this was JS-related.

[pushfoo]

Recap of my current thoughts:

• Furo minifies its JS when building locally, which is annoying
• Current builds of furo may require subtly different class names. Example: current and current-page for the outer <li>, and current on the <a> wrapped inside:
  
• Overriding the scroll handler in furo.js might be the way to go
• I'm not sure if maintaining our own custom vendored version of it is a good idea yet

[sabadam32]

Thanks for the clarification @cspotcode. I am not super familiar with tox yet but I will look into this.

[sabadam32]

Added PR to fix the color boxes. The transparent swatches will show a checkered background in the back. Right now there is only transparent black, which has an opacity of 0 so it looks like no color at all. I don't see any others that have transparency. It is there if we add any.

[sabadam32]

Required by #1429