Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Assort doc files into appropriate subfolders for easier navigation #79160

Merged
merged 4 commits into from
Jan 16, 2025

Conversation

moxian
Copy link
Contributor

@moxian moxian commented Jan 14, 2025

Summary

Infrastructure "The doc folder has been restructured for easier navigation"

Purpose of change

Making the docs easier to navigate, because they are a bit of a mess right now, and it's very hard to discover the file you want to read if you don't already know the filename.

Describe the solution

Have four distinct subfolders in doc/ directory:

  • compiling c++ - for all things C++.
  • JSON - for all things JSON. Technical documentation on how to add content.
  • design-balance-lore - for design-level documentation on what content to add.
  • user-guides - for the few doc pages that we expose to the end-user

Move the doc files into one of the four folders above, if appropriate

Grep codebase for .md string, and update the old links to point to new paths, when appropriate.

Describe alternatives you've considered

  • use different names for the folders, such as code for c++ and content for JSON. But in the end I decided that content is a bit too ambiguous with design, and I didn't want to create an extra folder level such as content/design/ vs content/json_reference because that felt unfair compared to a single level of C++.
    • Edit: changed to c++ anyway due to comments

Testing

Clicked around the docs in my branch on github - https://github.com/moxian/Cataclysm-DDA/tree/doc-shuffle . Seems to work but obviously was not able to check every link..

(I'm also hoping we have a CI check that'd yell at me if I missed something, but I'm not sure we do..)

Additional context

The former "Lore" folder was renamed to design-balance-lore because, turns out, it covered the design and balance aspects of the game pretty thoroughly, and was not focused exclusively on the narrative as the name would suggest.

The problem I was originally trying to solve here is that it was invariably taking me way more time than neccessary to locate instructions on how to use astyle/clang-tidy/other things inside DEVELOPER_TOOLING.md to the point that by now I have memorized how to actually use them, but I would still struggle locating the docs. This stemmed from the fact that DEVELOPER_TOOLING.md is situated in the sea of completely unrelated json docs, and one needs to know the exact name beforehand in order to find it.
So I simply moved DEVELOPER_TOOLING.md closer to the compiler-related docs in COMPILING/. And then moved CODE_STYLE.md there as well, because of course that's directly related (and if you're doing json changes you don't care about that one)

But then the next logical step is to move json-related docs to the json-named folder... and design-related files design folder... and here we are...

@github-actions github-actions bot added <Documentation> Design documents, internal info, guides and help. NPC / Factions NPCs, AI, Speech, Factions, Ownership Info / User Interface Game - player communication, menus, etc. [JSON] Changes (can be) made in JSON Missions Quests and missions Map / Mapgen Overmap, Mapgen, Map extras, Map display Code: Tests Measurement, self-control, statistics, balancing. [C++] Changes (can be) made in C++. Previously named `Code` [Markdown] Markdown issues and PRs [Python] Code made in Python Code: Tooling Tooling that is not part of the main game but is part of the repo. Mechanics: Enchantments / Spells Enchantments and spells labels Jan 14, 2025
@github-actions github-actions bot requested a review from KorGgenT January 14, 2025 20:44
Copy link
Contributor

@github-actions github-actions bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Auto-requesting reviews from non-collaborators: @jbytheway

@github-actions github-actions bot added Code: Infrastructure / Style / Static Analysis Code internal infrastructure and style astyled astyled PR, label is assigned by github actions json-styled JSON lint passed, label assigned by github actions labels Jan 14, 2025
@github-actions github-actions bot added the BasicBuildPassed This PR builds correctly, label assigned by github actions label Jan 15, 2025
@Procyonae
Copy link
Contributor

While I appreciate we barely have any C++ docs lumping them into compiling seems weird to me, I imagine peeps who find the compiling docs originally through github links would then outright ignore that folder once they're setup. (just renaming the folder to c++ would be fine imo)
On that topic this will need someone with wiki perms to go through and fix any doc links that got moved after it's merged. (Or we could just fina remove the wiki and move the rest to docs which I would have done by now if I had perms)

@github-actions github-actions bot added Code: Build Issues regarding different builds and build environments ImGui Anything related to the new ImGui UI for SDL/tiles or ImTui for curses builds labels Jan 15, 2025
@GuardianDll GuardianDll merged commit 69a4eb7 into CleverRaven:master Jan 16, 2025
30 of 32 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
astyled astyled PR, label is assigned by github actions BasicBuildPassed This PR builds correctly, label assigned by github actions [C++] Changes (can be) made in C++. Previously named `Code` Code: Build Issues regarding different builds and build environments Code: Infrastructure / Style / Static Analysis Code internal infrastructure and style Code: Tests Measurement, self-control, statistics, balancing. Code: Tooling Tooling that is not part of the main game but is part of the repo. <Documentation> Design documents, internal info, guides and help. ImGui Anything related to the new ImGui UI for SDL/tiles or ImTui for curses builds Info / User Interface Game - player communication, menus, etc. [JSON] Changes (can be) made in JSON json-styled JSON lint passed, label assigned by github actions Map / Mapgen Overmap, Mapgen, Map extras, Map display [Markdown] Markdown issues and PRs Mechanics: Enchantments / Spells Enchantments and spells Missions Quests and missions NPC / Factions NPCs, AI, Speech, Factions, Ownership [Python] Code made in Python
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants