Archipelago icon indicating copy to clipboard operation
Archipelago copied to clipboard

Webhost, Docs: Add sphinx autodocs to webhost and a github.io page

Open alwaysintreble opened this issue 11 months ago • 3 comments

What is this fixing or adding?

Adds /docs and extended pages to webhost that gets built on deployment, as well as a github pages reference that gets built whenever relevant files on main are modified. Currently builds autodocs for most of the primary files world devs should care for and a few of the dev facing documents. will likely move all of the dev documents into it but need decisions on what that layout should look like. currently since the pages are built from a template regardless of source, they look the same in both places. slightly problematic currently, since the header links are nice to have on the webhost version, but they're broken on the github pages version. still needs styling improvements as the layout is fairly borked.

How was this tested?

https://alwaysintreble.github.io/Archipelago/

If this makes graphical changes, please attach screenshots.

Screenshot_127 Screenshot_128

alwaysintreble avatar Mar 06 '24 03:03 alwaysintreble

In the upper screenshot

  • The uppercase FILL is really bad.
  • The background feels too noisy - I would go for the grass one we have in the guides and make the darker background thing span the whole sphinx block.
  • The vertical alignment of the white text in the blue bars is broken.

The second screenshot (or github.io link):

  • Absolutely needs either a darker "white" as the primary background color or a dark mode that's turned on by default.

Content-wise:

  • I think the docs should be above the API and the two sections be labeled somehow (so it's easier to see what's API and what's doc).
  • The "world api" needs to be renamed to "world api overview" or "world api guide".
  • The (world) api doc(s) should reference the spinx api docs to clarify that there may be more.

black-sliver avatar Apr 08 '24 23:04 black-sliver

After a discussion on voice, I think the content of this page on the WebHost is distinct enough from the rest of the content on the site to justify a distinct theme. It's going to use the same style as the second screenshot.

LegendaryLinux avatar Apr 12 '24 00:04 LegendaryLinux

I still don't think it's great to have a .bat and a Makefile and a ton of .rst files, when that could all be solved in a python script that generates the sphinx output. However cleaning this up can be done separately, depending on how hard it is to maintain the current system. The two things mentioned above are real problems imo though.

black-sliver avatar Apr 24 '24 07:04 black-sliver