docs!: new documentation page

[scarf005]

Summary

https://docs.cataclysmbn.org/en/

SUMMARY: Infrastructure "Create a new documentation page for better accessibility"

Purpose of change

original reply

• better accessibility.
• centralize knowledge.
• looks cool

Describe the solution

• site built with starlight static site generator
• organized documentation files into tutorial, guides, reference and explanation
• added AGPL license for docs site

Testing

original questions

• Add an automated workflow that'll upload contents of our doc folder to the website
• Include autogenerated documentation for cmd args and Lua bindings
• Other documentations in the repository that could be centralized and added to the upload
• Migrate GitHub wiki
• Migrate C++ documentation available on gh pages?
• Should the website track different documentation for different builds/releases, and if so, then how? How could this play out with the potential website for the game ( I can make a website for the game #3062 )

Describe alternatives you've considered

#3062 may handle documentations better than this, but it wouldn't hurt to have a quick docs page running.

Additional context

after the merge only the URL (cataclysm.org) redirect needs to be done

[olanti-p]

After a brief glance:

1. Looks cool Much centralized, such convenient. The search feels quite good, it's faster than GitHub and you don't get many irrelevant results you often get from the repo.
2. Does this support offline builds, so we could bundle prebuilt website with the releases? With no internet connection, players or modders would be able to just open the game folder, navigate to the doc folder, double click index.html and view the docs with the browser.

Offline builds like that would actually solve the version tracking problem

Should the website track different documentation for different builds/releases, and if so, then how?

...since the user would be able to simply download the needed release off GitHub and view the docs bundled with it.

3. On that topic, it would be nice to have a note that is linked from the main README.md and explains where to find the documentation in the filesystem and how to build & run the website locally. Yes, it's explained in doc/src/content/docs/en/contributing/docs.mdx, but you wouldn't find that file unless you chance on it, and relying on the online website isn't quite robust since the website (or the build process) may change in the future.

Regarding the website itself, some aspects could use some polish, but as I understand it comes with time.

4. The 2D navigation is a bit jarring. There's a sidebar on the left with the topics, but there are also tabs with categories on the top, and sometimes clicking a topic would silently switch the category, meaning you're presented with a completely new set of topics.
5. Many pages have inconsistent naming styles (lower case vs normal text vs caps) and broken ToCs on the right side.
6. Some pages cover many topics, while some topics can have multiple pages. Some wiki pages, for once, just mirror existing doc pages or should be integrated into the docs or removed.
7. Maybe a less green color theme

As to the docs themselves, we still have many outdated docs that mention DDA, or (not) mention fields and functionality that (is no longer)/(should be) there, so some kind of warning on the website would be warranted.

[olanti-p]

Is this supposed to be here? Looks like a leftover from some starlight template.

[scarf005]

yeah, i've edited a bit but it's still leftover from default template. i'll symlink with docs page building guide instead.

[scarf005]

Does this support offline builds, so we could bundle prebuilt website with the releases?

yes, it can be done via running pnpm build on doc/ directory, and i think bundling could be done via copy-pasting doc/dist/. the bundle is 18MiB which isn't small, maybe we could only include them in PC build.

EDIT: starlight doesn't support file-based routing yet, it might take more time to bundle this, as currently the only way to read docs offline is to run a dev server.

it would be nice to have a note that is linked from the main README.md and explains where to find the documentation in the filesystem and how to build & run the website locally.

ok, will

• change the links in README.md to use relative path to doc/
• update doc/README.md to add proper guide to building the page

The 2D navigation is a bit jarring. There's a sidebar on the left with the topics, but there are also tabs with categories on the top, and

sometimes clicking a topic would silently switch the category

do you mean contributing/json style? yeah, links that jumps to another navbar was a bad idea.

Many pages have inconsistent naming styles (lower case vs normal text vs caps)

do you mean filenames? i'll do it rn

broken ToCs on the right side.

could you point out where? i'll try to fix them

Some wiki pages, for once, just mirror existing doc pages or should be integrated into the docs or removed.

wiki category was makeshift, will apply changes

Maybe a less green color theme

done.

As to the docs themselves, we still have many outdated docs that mention DDA, or (not) mention fields and functionality that (is no longer)/(should be) there, so some kind of warning on the website would be warranted.

will add.

[olanti-p]

could you point out where? i'll try to fix them

Sure. Here's all the issues I could find, including ToC problems:

Broken links:

• /dev/guides/building/vs_vcpkg/#code-style has a broken link to astyle extension
• /dev/reference/tooling/#json-style dead link
• /dev/reference/tooling/#clang-tidy dead link
• /dev/explanation/points_coordinates/#point-types dead link to coordinates.h (maybe simply remove the link?)
• /i18n/reference/gender/ dead link to NPC docs
• /i18n/reference/translation/#lua dead link to Lua docs
• /contribute/docs/#update-existing-docs dead link in step 5
• /mod/json/reference/creatures/np_cs/ dead link to missions doc

Remaining cases of inconsistent case in left sidebar:

• /mod/json/guides/building_undead_people_tileset/ lowercase
• /mod/json/explanation/melee_weapons/melee_balance_spreadsheet/ lowercase "melee weapons"
• /dev/explanation/best_practices/ lowercase
• /mod/json/reference/creatures/new_mutations/ lowercase
• /mod/json/reference/graphics/tileset/ capital case, plus all 'creatures'/'graphics'/'items'/'map' are lowercase
• /mod/json/reference/map/mapgen/ capital case
• /mod/json/reference/map/weather_type/ should either be lowercase as weather_type, or without _ as "Weather types"
• /contribute/changelog/ lowercase in left sidebar.

Issues with ToC in right sidebar. These seems to have 1 thing in common: the missing headers look larger then the ones with links.

• /mod/json/reference/ingame_debugging_tools/ no ToC
• /dev/guides/building/makefile/#additional-notes broken right sidebar: there should be a Mac OS X section, and following sections be children of it. There should also be Windows section, right after "Mac OS X Troubleshooting" in left sidebar
• /mod/json/explanation/melee_weapons/melee_balance_spreadsheet/ There's 2 "Overview" entries in right sidebar
• /mod/json/reference/creatures/monsters/#chance no "Modding" in right sidebar, no "Monster special attack types"
• /mod/json/reference/creatures/np_cs/#dialogue-effects There are no subdivisions to Missions, Stats / Morale, etc.
• /mod/json/reference/json_info/#other-formatting There's no section for "Description and content of each JSON file". There's no section for "Scenarios" (should be after /mod/json/reference/json_info/#clothing_mod), or "Starting locations", or "Mutation overlay ordering", or "MOD_INFO" (which also has a broken link), or "MOD tileset"
• /mod/json/explanation/game_balance/#base-barrel-length no "LIQUID" or "Diamond weapons" (near the bottom of the file)
• /contribute/changelog/ no separation per game versions

Misc feedback for individual pages:

• /game/lore/ could use a spoiler warning, it has major spoilers
• /dev/guides/building/cygwin/ has note as banner and broken link, but /dev/guides/building/msys/ has same note as plain text and link works
• /dev/explanation/design_document/ links to GitHub wiki instead of website
• /lua/guides/binding/ empty "Tutorial" section for Lua in left sidebar
• /mod/json/reference/soundpacks/#json-format-sound-effects-list has weird capitalization of text

These issues are probably not caused by this PR:

• In many places docs themselves are outdated, but that's out of scope of this PR
• /dev/guides/building/cmake/#build-for-visual-studio--msbuild has broken links to SDL dependencies
• /dev/guides/building/makefile/#cross-compile-to-mac-os-x-from-linux has broken link to PR
• /dev/guides/building/makefile/#setup has broken link to osxcross readme
• /dev/guides/building/makefile/#cross-compile-to-android-from-linux has 2 dead links to sdl android project template
• /dev/guides/building/makefile/#simple-build-using-homebrew links to "cataclysm formula", but it's for DDA, we don't have one for BN AFAIK
• /dev/guides/building/makefile/#sdl more dead SDL links
• /dev/guides/testing/#_top dead link to Catch2 tutorial
• /dev/reference/tooling/#astyle-extensions-for-visual-studio in VS2022 section, dead link to readme of my fork of the extension (btw, now that there's a PR with VS2022 support in the original repo, we may want to make a fork with that PR merged instead of mine ad-hoc solution)
• /dev/reference/tooling/#custom-clang-tidy-plugin in "Build clang-tidy with custom checks" section, dead link to "the .whl installer" (not sure what it's supposed to mean)
• /dev/reference/tooling/#include-what-you-use dead link in paragraph "IWYU has a concept of associated headers"
• /mod/json/explanation/melee_weapons/melee_balance_spreadsheet/ dead link to google doc

[olanti-p]

Unfortunately pnpm is not available in some countries, I've PR'd pure npm instructions as scarf005#18

[scarf005]

Unfortunately pnpm is not available in some countries

could you elaborate further?

[olanti-p]

They're geo-blocking Russian IPs (for obvious reasons), at least, maybe other countries.

[olanti-p]

Other documentations in the repository that could be centralized and added to the upload

Looks like the only docs left worth including are the contents of lang/notes/. They're mentioned in /i18n/reference/edge_cases/ (former TRANSLATING.md) and have some useful info, but people frequently overlook them, and on website they should get better visibility.

There are other small markdown or text files scattered here and there, but none of them seem to be worth putting on the website, as they mostly describe the workings of specific directories they belong to:

./data/json/mapgen/lab/README.md
./data/json/external_tileset/External Tileset Info.md
./data/mods/DinoMod/README.md
./data/mods/DinoMod/DESIGN.md
./data/mods/TEST_DATA/README.md
./data/mods/CRT_EXPANSION/readme/README.md
./data/mods/No_Hope/README.md
./data/mods/Aftershock/crafting_system.md
./data/mods/Aftershock/README.md
./data/mods/Magiclysm/lore.md
./data/mods/Magiclysm/magic_balance.md
./src/lua/LICENSE.md
./src/lua/README.md
./tests/data/cata_libintl/README.txt
./data/mods/Mundane_Zombies/z2keep.txt
./data/mods/Graphical_Overmap/readme.txt
./data/mods/alt_map_key/readme.txt
./src/sol/changes.txt

[scarf005]

@olanti-p do you think this is ready for merging?

[olanti-p]

Yes.
It's in working state and all immediate problems have been resolved, I think it's ready to go.