docs!: new documentation page #3121

scarf005 · 2023-09-07T14:10:10Z

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:

~~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.
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.

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.

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.
Many pages have inconsistent naming styles (lower case vs normal text vs caps) and broken ToCs on the right side.
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.
~~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.

doc/src/content/docs/en/lua/reference/lua.md

olanti-p · 2023-09-11T19:56:57Z

doc/README.md

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

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

deno.jsonc

doc/Blank Building Template.txt

doc/src/content/docs/en/dev/guides/building/cmake.md

scarf005 · 2023-09-11T23:11:56Z

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.

see: cataclysmbnteam#3121 (comment) Co-authored-by: olanti-p <[email protected]>

olanti-p · 2023-09-15T23:23:50Z

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:

Co-authored-by: olanti-p <[email protected]>

BN does not support homebrew

LICENSE.txt

olanti-p · 2023-09-20T19:22:45Z

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

scarf005 · 2023-09-20T20:37:11Z

Unfortunately pnpm is not available in some countries

could you elaborate further?

olanti-p · 2023-09-20T20:48:30Z

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

olanti-p · 2023-09-20T21:59:52Z

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 · 2023-09-20T23:18:41Z

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

olanti-p · 2023-09-20T23:30:24Z

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

github-actions bot added src changes related to source code. JSON related to game datas in JSON format. labels Sep 7, 2023

scarf005 force-pushed the docs branch 14 times, most recently from 9832c18 to 1806337 Compare September 11, 2023 15:39

scarf005 requested a review from olanti-p September 11, 2023 15:40

scarf005 marked this pull request as ready for review September 11, 2023 15:40

scarf005 force-pushed the docs branch from 1806337 to e7a1d57 Compare September 11, 2023 15:42

olanti-p reviewed Sep 11, 2023

View reviewed changes

scarf005 added a commit to scarf005/Cataclysm-BN that referenced this pull request Sep 12, 2023

docs: remove blank_building_template.md

0c9f603

see: cataclysmbnteam#3121 (comment) Co-authored-by: olanti-p <[email protected]>

scarf005 force-pushed the docs branch from 3db8528 to a20a7c7 Compare September 12, 2023 02:06

scarf005 requested a review from olanti-p September 12, 2023 02:06

scarf005 force-pushed the docs branch from ae6667e to 9215f6d Compare September 12, 2023 02:18

scarf005 added a commit to scarf005/Cataclysm-BN that referenced this pull request Sep 13, 2023

docs: remove blank_building_template.md

da6c35d

see: cataclysmbnteam#3121 (comment) Co-authored-by: olanti-p <[email protected]>

scarf005 force-pushed the docs branch from 9215f6d to 9ae1528 Compare September 13, 2023 00:14

olanti-p mentioned this pull request Sep 15, 2023

☂️ Outdated documentation #3148

Open

5 tasks

docs(lua): add front matter

22342b2

scarf005 and others added 5 commits September 17, 2023 15:22

fix(docs): broken links and cases

d21d0ce

Co-authored-by: olanti-p <[email protected]>

docs: toc issues

a025a65

Co-authored-by: olanti-p <[email protected]>

docs: fix broken links, split JSON_INFO and lore

bfbc4af

Co-authored-by: olanti-p <[email protected]>

docs: do not try to fix absolute URL

396822c

docs: more dead links and issues

ce8e1a2

Co-authored-by: olanti-p <[email protected]>

scarf005 force-pushed the docs branch from 9ae1528 to f9ecaab Compare September 17, 2023 06:59

docs: remove homebrew section

55be1a8

BN does not support homebrew

scarf005 force-pushed the docs branch from a197fe6 to 55be1a8 Compare September 17, 2023 07:01

scarf005 mentioned this pull request Sep 17, 2023

chore: license new scripts under AGPL-3.0-only #3169

Merged

olanti-p reviewed Sep 17, 2023

View reviewed changes

LICENSE.txt Outdated Show resolved Hide resolved

scarf005 force-pushed the docs branch from 2ef2d40 to 6e26cb5 Compare September 17, 2023 23:50

scarf005 requested a review from olanti-p September 17, 2023 23:50

scarf005 added 2 commits September 18, 2023 08:52

docs: add license

8cdee0d

build: fix deno task typo

af6fd1e

scarf005 force-pushed the docs branch from 8307498 to af6fd1e Compare September 17, 2023 23:52

docs: recommend makefile (atm)

8d57538

olanti-p added 2 commits September 21, 2023 05:48

build: npm lockfile

b08c400

docs: add npm instructions to docs tutorial

916e0e9

style(autofix.ci): automated formatting

18483b0

olanti-p approved these changes Sep 20, 2023

View reviewed changes

scarf005 merged commit 869a914 into cataclysmbnteam:upload Sep 20, 2023
18 checks passed

scarf005 deleted the docs branch September 20, 2023 23:41

This was referenced Sep 22, 2023

docs: lang/notes #3207

Merged

create homepage for BN #1702

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs!: new documentation page #3121

docs!: new documentation page #3121

scarf005 commented Sep 7, 2023 •

edited

Loading

olanti-p left a comment

olanti-p Sep 11, 2023

scarf005 Sep 11, 2023

scarf005 commented Sep 11, 2023 •

edited

Loading

olanti-p commented Sep 15, 2023 •

edited by scarf005

Loading

olanti-p commented Sep 20, 2023 •

edited

Loading

scarf005 commented Sep 20, 2023

olanti-p commented Sep 20, 2023

olanti-p commented Sep 20, 2023

scarf005 commented Sep 20, 2023

olanti-p commented Sep 20, 2023

docs!: new documentation page #3121

docs!: new documentation page #3121

Conversation

scarf005 commented Sep 7, 2023 • edited Loading

Summary

Purpose of change

Describe the solution

Testing

Describe alternatives you've considered

Additional context

olanti-p left a comment

Choose a reason for hiding this comment

olanti-p Sep 11, 2023

Choose a reason for hiding this comment

scarf005 Sep 11, 2023

Choose a reason for hiding this comment

scarf005 commented Sep 11, 2023 • edited Loading

olanti-p commented Sep 15, 2023 • edited by scarf005 Loading

olanti-p commented Sep 20, 2023 • edited Loading

scarf005 commented Sep 20, 2023

olanti-p commented Sep 20, 2023

olanti-p commented Sep 20, 2023

scarf005 commented Sep 20, 2023

olanti-p commented Sep 20, 2023

scarf005 commented Sep 7, 2023 •

edited

Loading

scarf005 commented Sep 11, 2023 •

edited

Loading

olanti-p commented Sep 15, 2023 •

edited by scarf005

Loading

olanti-p commented Sep 20, 2023 •

edited

Loading