Merge pull request #79160 from moxian/doc-shuffle

Assort doc files into appropriate subfolders for easier navigation
CleverRaven · Jan 16, 2025 · 69a4eb7 · 69a4eb7
2 parents 3e523d0 + fd15593
commit 69a4eb7
Show file tree

Hide file tree

Showing 105 changed files with 94 additions and 94 deletions.
diff --git a/.devcontainer/cross-compile/Dockerfile b/.devcontainer/cross-compile/Dockerfile
@@ -31,7 +31,7 @@ RUN apt-get update && export DEBIAN_FRONTEND=noninteractive \
 RUN apt-get -y install qtbase5-dev qtchooser qt5-qmake qtbase5-dev-tools
 
 # [Optional] comment out this section unless you want to cross-compile from Linux to Windows
-# This section should align with doc/COMPILING/COMPILING.md#cross-compile-to-windows-from-linux
+# This section should align with doc/c++/COMPILING.md#cross-compile-to-windows-from-linux
 # With the exception of the installation of packages that are already installed earlier in the Dockerfile
 # Like: astyle, cmake
 RUN apt-get -y install autoconf automake autopoint bash bison bzip2 flex gettext git g++ \

diff --git a/.github/workflows/linter.yml b/.github/workflows/linter.yml
@@ -40,4 +40,4 @@ jobs:
       uses: reviewdog/action-suggester@v1
       if: ${{ always() }}
       with:
-        tool_name: '[JSON & C++ formatters](https://github.com/CleverRaven/Cataclysm-DDA/blob/master/doc/DEVELOPER_TOOLING.md)'
+        tool_name: '[JSON & C++ formatters](https://github.com/CleverRaven/Cataclysm-DDA/blob/master/doc/c++/DEVELOPER_TOOLING.md)'
diff --git a/.github/workflows/toc.yml b/.github/workflows/toc.yml
@@ -3,7 +3,7 @@ on:
     branches:
     - master
     paths:
-    - 'doc/JSON_INFO.md'
+    - 'doc/JSON/JSON_INFO.md'
 name: TOC Generator
 permissions:
   contents: read
@@ -15,17 +15,17 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - run: npx doctoc doc/JSON_INFO.md --github
+      - run: npx doctoc doc/JSON/JSON_INFO.md --github
       - name: Create Pull Request
         uses: peter-evans/create-pull-request@v6
         with:
           commit-message: Update the table of contents
           branch: update-toc
           token: ${{ secrets.TX_PR_CREATOR }}
-          title: Update the table of contents in doc/JSON_INFO.md
+          title: Update the table of contents in doc/JSON/JSON_INFO.md
           body: |
             ```sh
             #### Summary
             None
-            npx doctoc doc/JSON_INFO.md --github
+            npx doctoc doc/JSON/JSON_INFO.md --github
             ```
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -211,7 +211,7 @@ message(STATUS "LOCALIZE                      : ${LOCALIZE}")
 message(STATUS "USE_XDG_DIR                   : ${USE_XDG_DIR}")
 message(STATUS "USE_HOME_DIR                  : ${USE_HOME_DIR}")
 message(STATUS "LANGUAGES                     : ${LANGUAGES}")
-message(STATUS "See doc/COMPILING/COMPILING-CMAKE.md for details and more info --")
+message(STATUS "See doc/c++/COMPILING-CMAKE.md for details and more info --")
 
 if (NOT MSVC)
     set(CATA_WARNINGS
@@ -255,7 +255,7 @@ if ("${CMAKE_SOURCE_DIR}" STREQUAL "${CMAKE_BINARY_DIR}")
             "This project requires an out of source build. \
              Remove the file 'CMakeCache.txt' found in this directory before continuing; \
              create a separate build directory and run 'cmake [options] <srcs>' from there. \
-             See doc/COMPILING/COMPILING-CMAKE.md for details and more info.")
+             See doc/c++/COMPILING-CMAKE.md for details and more info.")
 endif ()
 
 #set(THREADS_USE_PTHREADS_WIN32 True)
@@ -284,7 +284,7 @@ if (TILES)
                 "This project requires SDL2 to be installed to compile in graphical mode.  \
                  Please install the SDL2 development libraries, \
                  or try compiling without -DTILES=1 for a text-only compilation. \
-                 See doc/COMPILING/COMPILING-CMAKE.md for details and more info.")
+                 See doc/c++/COMPILING-CMAKE.md for details and more info.")
     endif ()
 
     message(STATUS "Searching for SDL2_TTF library --")
@@ -294,7 +294,7 @@ if (TILES)
                 "This project requires SDL2_ttf to be installed to compile in graphical mode. \
                  Please install the SDL2_ttf development libraries, \
                  or try compiling without -DTILES=1 for a text-only compilation. \
-                 See doc/COMPILING/COMPILING-CMAKE.md for details and more info.")
+                 See doc/c++/COMPILING-CMAKE.md for details and more info.")
     endif ()
 
     message(STATUS "Searching for SDL2_image library --")
@@ -304,7 +304,7 @@ if (TILES)
                 "This project requires SDL2_image to be installed to compile in graphical mode. \
                  Please install the SDL2_image development libraries, \
                  or try compiling without -DTILES=1 for a text-only compilation. \
-                 See doc/COMPILING/COMPILING-CMAKE.md for details and more info.")
+                 See doc/c++/COMPILING-CMAKE.md for details and more info.")
     endif ()
     add_definitions(-DTILES)
 endif ()
@@ -358,7 +358,7 @@ if (CURSES)
                 "This project requires ncurses to be installed to be compiled in text-only mode. \
                  Please install the ncurses development libraries, \
                  or try compiling with -DTILES=1 for a graphical compilation. \
-                 See doc/COMPILING/COMPILING-CMAKE.md for details and more info")
+                 See doc/c++/COMPILING-CMAKE.md for details and more info")
     endif ()
     if (NOT DYNAMIC_LINKING)
         set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -DNCURSES_STATIC")
@@ -374,7 +374,7 @@ if (SOUND)
         message(FATAL_ERROR
                 "You need the SDL2_mixer development library \
                     to be able to compile with sound enabled. \
-                    See doc/COMPILING/COMPILING-CMAKE.md for details and more info.")
+                    See doc/c++/COMPILING-CMAKE.md for details and more info.")
     endif()
 endif ()
 

diff --git a/ISSUES.md b/ISSUES.md
@@ -48,7 +48,7 @@ You can update issues with labels using comment-commands. First, open a PR addin
 
 ### Questions
 
-You should direct your questions to the forum or ask on IRC. You should also read the included documentation and additional text files, e.g. [COMPILING.md](doc/COMPILING/COMPILING.md) if you have problems building.
+You should direct your questions to the forum or ask on IRC. You should also read the included documentation and additional text files, e.g. [COMPILING.md](doc/c++/COMPILING.md) if you have problems building.
 
 ## Bounties
 

diff --git a/README.md b/README.md
@@ -45,12 +45,12 @@ Ncurses and tiles versions are available in the [official repos](https://tracker
 
 ## Compile
 
-Please read [COMPILING.md](doc/COMPILING/COMPILING.md) - it covers general information and more specific recipes for Linux, OS X, Windows and BSD. See [COMPILER_SUPPORT.md](doc/COMPILING/COMPILER_SUPPORT.md) for details on which compilers we support. And you can always dig for more information in [doc/](https://github.com/CleverRaven/Cataclysm-DDA/tree/master/doc).
+Please read [COMPILING.md](doc/c++/COMPILING.md) - it covers general information and more specific recipes for Linux, OS X, Windows and BSD. See [COMPILER_SUPPORT.md](doc/c++/COMPILER_SUPPORT.md) for details on which compilers we support. And you can always dig for more information in [doc/](https://github.com/CleverRaven/Cataclysm-DDA/tree/master/doc).
 
 We also have the following build guides:
-* Building on Windows with `MSYS2` at [COMPILING-MSYS.md](doc/COMPILING/COMPILING-MSYS.md)
-* Building on Windows with `vcpkg` at [COMPILING-VS-VCPKG.md](doc/COMPILING/COMPILING-VS-VCPKG.md)
-* Building with `cmake` at [COMPILING-CMAKE.md](doc/COMPILING/COMPILING-CMAKE.md)  (*unofficial guide*)
+* Building on Windows with `MSYS2` at [COMPILING-MSYS.md](doc/c++/COMPILING-MSYS.md)
+* Building on Windows with `vcpkg` at [COMPILING-VS-VCPKG.md](doc/c++/COMPILING-VS-VCPKG.md)
+* Building with `cmake` at [COMPILING-CMAKE.md](doc/c++/COMPILING-CMAKE.md)  (*unofficial guide*)
 
 ## Contribute
 

diff --git a/data/fontdata.json b/data/fontdata.json
@@ -1,5 +1,5 @@
 {
-  "//1": "See docs/FONT_OPTIONS.md for how to configure your fonts.",
+  "//1": "See docs/user-guides/FONT_OPTIONS.md for how to configure your fonts.",
   "typeface": [
     { "path": "data/font/Terminus.ttf", "hinting": "Bitmap" },
     "data/font/unifont.ttf"

diff --git a/data/mods/translate-dialogue/README.md b/data/mods/translate-dialogue/README.md
@@ -26,5 +26,5 @@ vvvvvvvvvvvvvvvvvvvvvvvvv
 Usage:
  * `cd path/to/Cataclysm-DDA/`
  * `python3 tools/json_tools/update-translate-dialogue-mod.py`
- * then lint via `json_formatter.cgi`, check `doc/JSON_STYLE.md`
+ * then lint via `json_formatter.cgi`, check `doc/JSON/JSON_STYLE.md`
  * You can also add `"//": "mod_update_script_compact"` to dynamic lines to make the script concatenate that line more compactly and without newlines, which is useful if the original dialog also uses concatenation.
diff --git a/data/raw/imgui_style.json b/data/raw/imgui_style.json
@@ -1,5 +1,5 @@
 {
-  "//": "See doc/COLOR.md for documentation on how to use this file.",
+  "//": "See doc/user-guides/COLOR.md for documentation on how to use this file.",
   "inherit_base_colors": false,
   "colors": {
 

diff --git a/doc/CONTRIBUTING.md b/doc/CONTRIBUTING.md
@@ -64,7 +64,7 @@ There are a couple of guidelines we suggest sticking to (see [#Example Workflow]
 ## Code Style
 
 Code style is enforced across the codebase by `astyle`.
-See [CODE_STYLE](../doc/CODE_STYLE.md) for details.
+See [CODE_STYLE](../doc/c++/CODE_STYLE.md) for details.
 
 ## Translations
 
@@ -268,7 +268,7 @@ When your PR should close an issue, please include [closing keywords](https://he
 
 ## Tooling support
 
-Various tools are available to help you keep your contributions conforming to the appropriate style. See [DEVELOPER_TOOLING.md](../doc/DEVELOPER_TOOLING.md) for more details.
+Various tools are available to help you keep your contributions conforming to the appropriate style. See [DEVELOPER_TOOLING.md](../doc/c++/DEVELOPER_TOOLING.md) for more details.
 
 ## Advanced Techniques
 
@@ -341,9 +341,9 @@ The test took 41.772 seconds
 
 It is recommended to habitually invoke make like ``make YOUR BUILD OPTIONS && make check``.
 
-If you're working with Visual Studio (and don't have `make`), see [Visual Studio-specific advice](../doc/COMPILING/COMPILING-VS-VCPKG.md#running-unit-tests).
+If you're working with Visual Studio (and don't have `make`), see [Visual Studio-specific advice](../doc/c++/COMPILING-VS-VCPKG.md#running-unit-tests).
 
-If you want/need to add a test, see [TESTING.md](../doc/TESTING.md)
+If you want/need to add a test, see [TESTING.md](../doc/c++/TESTING.md)
 
 ## In-game testing, test environment and the debug menu
 

diff --git a/doc/FREQUENTLY_MADE_SUGGESTIONS.md b/doc/FREQUENTLY_MADE_SUGGESTIONS.md
@@ -142,12 +142,12 @@ Currently it’s way too easy to accumulate NPC followers and end up becoming ef
 #### Psychic powers: mod only
 
 Not happening, it simply doesn’t fit the theme of the game.
-However, Mind Over Matter is distributed with the game, and adds psychic powers. See [MAGIC.md](MAGIC.md) for more info.
+However, Mind Over Matter is distributed with the game, and adds psychic powers. See [MAGIC.md](JSON/MAGIC.md) for more info.
 
 #### Magic powers: mod only
 
 Not happening, it simply doesn’t fit the theme of the game.
-However, the Magiclysm mod is distributed with the game and is very extensible in JSON to support other systems of magic, such as Mind Over Matter. This infrastructure is also used with EOC's and activated mutations in the base game. See [MAGIC.md](MAGIC.md) for more info.
+However, the Magiclysm mod is distributed with the game and is very extensible in JSON to support other systems of magic, such as Mind Over Matter. This infrastructure is also used with EOC's and activated mutations in the base game. See [MAGIC.md](JSON/MAGIC.md) for more info.
 
 #### Remove skill rust: no
 

diff --git a/doc/ARTIFACTS.md → doc/JSON/ARTIFACTS.md b/doc/ARTIFACTS.md → doc/JSON/ARTIFACTS.md
diff --git a/doc/BASECAMP.md → doc/JSON/BASECAMP.md b/doc/BASECAMP.md → doc/JSON/BASECAMP.md
@@ -93,7 +93,7 @@ The `"faction_base_camp_8"` upgrade mission can be performed after `"faction_bas
 
 ## mapgen update JSON
 
-These are standard mapgen update JSON; see [the MAPGEN docs](doc/MAPGEN.md) for
+These are standard mapgen update JSON; see [the MAPGEN docs](./MAPGEN.md) for
 more details.  Each one should change a localized portion of the camp map and
 should, as much as possible, be independent of any other pieces of
 mapgen update for the basecamp upgrade path.  Obviously, some bits are going to
@@ -139,7 +139,7 @@ In this situation, you can define multiple upgrade options with a single recipe
 and a single mapgen update.  This works as follows.
 
 Put one or more mapgen parameters in the mapgen update.  Mapgen parameters are
-documented in [the MAPGEN docs](doc/MAPGEN.md).  Each parameter should be at
+documented in [the MAPGEN docs](./MAPGEN.md).  Each parameter should be at
 OMT scope and have a set of options defined e.g. via `"distribution"`, but the
 weights of the different options do not matter; the player will choose between
 them rather than a random choice.

diff --git a/doc/CLIMBING.md → doc/JSON/CLIMBING.md b/doc/CLIMBING.md → doc/JSON/CLIMBING.md
diff --git a/doc/EFFECTS_JSON.md → doc/JSON/EFFECTS_JSON.md b/doc/EFFECTS_JSON.md → doc/JSON/EFFECTS_JSON.md
diff --git a/doc/EFFECT_ON_CONDITION.md → doc/JSON/EFFECT_ON_CONDITION.md b/doc/EFFECT_ON_CONDITION.md → doc/JSON/EFFECT_ON_CONDITION.md
diff --git a/doc/EXAMINE.md → doc/JSON/EXAMINE.md b/doc/EXAMINE.md → doc/JSON/EXAMINE.md
diff --git a/doc/FACTIONS.md → doc/JSON/FACTIONS.md b/doc/FACTIONS.md → doc/JSON/FACTIONS.md
diff --git a/doc/GUIDE_COMESTIBLES.md → doc/JSON/GUIDE_COMESTIBLES.md b/doc/GUIDE_COMESTIBLES.md → doc/JSON/GUIDE_COMESTIBLES.md
diff --git a/doc/HELP_MENU.md → doc/JSON/HELP_MENU.md b/doc/HELP_MENU.md → doc/JSON/HELP_MENU.md
@@ -10,8 +10,8 @@ Each category is made up of a json object which for mods can be placed anywhere
 | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `"type"`     | (required) must be `"help"`                                                                                                                                                                                                                                                                           |
 | `"order"`    | (required) integer, where this category should appear in the list relative to others from the same source, with 0 being first. Must be unique per source (Every mod can start from 0). Each mods categories are appended to the end of the list per their load order.                                 |
-| `"name"`     | (required) string, name of the category, can use [color tags](COLOR.md#color-tags)                                                                                                                                                                                                                  |
-| `"messages"` | (required) array of strings, each string respresents a new line seperated paragraph containing information for this category, can use [color tags](COLOR.md#color-tags) and [keybind tags](#keybind-tags). Seperated mainly for ease of editing the json as `\n` lets you add newlines within strings |
+| `"name"`     | (required) string, name of the category, can use [color tags](/doc/user-guides/COLOR.md#color-tags)                                                                                                                                                                                                                  |
+| `"messages"` | (required) array of strings, each string respresents a new line seperated paragraph containing information for this category, can use [color tags](/doc/user-guides/COLOR.md#color-tags) and [keybind tags](#keybind-tags). Seperated mainly for ease of editing the json as `\n` lets you add newlines within strings |
 
 ### Keybind tags
 

diff --git a/doc/ITEM_DISASSEMBLY.md → doc/JSON/ITEM_DISASSEMBLY.md b/doc/ITEM_DISASSEMBLY.md → doc/JSON/ITEM_DISASSEMBLY.md
diff --git a/doc/ITEM_SPAWN.md → doc/JSON/ITEM_SPAWN.md b/doc/ITEM_SPAWN.md → doc/JSON/ITEM_SPAWN.md
diff --git a/doc/JSON_FLAGS.md → doc/JSON/JSON_FLAGS.md b/doc/JSON_FLAGS.md → doc/JSON/JSON_FLAGS.md
diff --git a/doc/JSON_INFO.md → doc/JSON/JSON_INFO.md b/doc/JSON_INFO.md → doc/JSON/JSON_INFO.md
@@ -3468,7 +3468,7 @@ Weakpoints only match if they share the same id, so it's important to define the
   "bash": 0,
   "cut": 0
 },
-"to_hit" {                                   // (Optional) To hit bonus values, omit if item isn't suited to be used as a melee weapon, see [GAME_BALANCE.md](GAME_BALANCE.md#to-hit-value) for individual value breakdowns.
+"to_hit" {                                   // (Optional) To hit bonus values, omit if item isn't suited to be used as a melee weapon, see [GAME_BALANCE.md](/doc/design-balance-lore/GAME_BALANCE.md#to-hit-value) for individual value breakdowns.
   "grip": "solid",                           // the item's grip value
   "length": "long",                          // the item's length value
   "surface": "point",                        // the item's striking surface value
@@ -3530,7 +3530,7 @@ For additional clarity, an item's `to_hit` bonus can be encoded as string of 4 f
     "balance": "neutral"   // one of "clumsy", "uneven", "neutral", or "good"
 }
 ```
-See [GAME_BALANCE.md](GAME_BALANCE.md#to-hit-value)
+See [GAME_BALANCE.md](/doc/design-balance-lore/GAME_BALANCE.md#to-hit-value)
 
 ### Ammo
 
@@ -3732,7 +3732,7 @@ Overrides the armor breathability, which is driven by armor material. Can be `IM
 
 ##### Layers
 
-What layer this piece of armor occupy. Can be `PERSONAL`, `SKINTIGHT`, `NORMAL`, `WAIST`, `OUTER`, `BELTED`, `AURA`, see [ARMOR_BALANCE_AND_DESIGN.md#layers](ARMOR_BALANCE_AND_DESIGN.md#layers) for details
+What layer this piece of armor occupy. Can be `PERSONAL`, `SKINTIGHT`, `NORMAL`, `WAIST`, `OUTER`, `BELTED`, `AURA`, see [ARMOR_BALANCE_AND_DESIGN.md#layers](/doc/design-balance-lore/ARMOR_BALANCE_AND_DESIGN.md#layers) for details
 
 ##### rigid_layer_only
 
@@ -4150,7 +4150,7 @@ Any Item can be a container. To add the ability to contain things to an item, yo
   "cut": 12
 },
 "flags" : ["CHOP"],    // Indicates special effects
-"to_hit" {             // (Optional) To hit bonus values, omit if item isn't suited to be used as a melee weapon, see [GAME_BALANCE.md](GAME_BALANCE.md#to-hit-value) for individual value breakdowns.
+"to_hit" {             // (Optional) To hit bonus values, omit if item isn't suited to be used as a melee weapon, see [GAME_BALANCE.md](/doc/design-balance-lore/GAME_BALANCE.md#to-hit-value) for individual value breakdowns.
   "grip": "solid",                           
   "length": "long",                          
   "surface": "point",                        
@@ -4326,7 +4326,7 @@ Alternately, every item (book, tool, armor, even food) can be used as a gunmod i
   "bash": 12,
   "cut": 0
 },
-"to_hit" {             // (Optional) To hit bonus values, omit if item isn't suited to be used as a melee weapon, see [GAME_BALANCE.md](GAME_BALANCE.md#to-hit-value) for individual value breakdowns.
+"to_hit" {             // (Optional) To hit bonus values, omit if item isn't suited to be used as a melee weapon, see [GAME_BALANCE.md](/doc/design-balance-lore/GAME_BALANCE.md#to-hit-value) for individual value breakdowns.
   "grip": "solid",                           
   "length": "long",                          
   "surface": "point",                        

diff --git a/doc/JSON_INHERITANCE.md → doc/JSON/JSON_INHERITANCE.md b/doc/JSON_INHERITANCE.md → doc/JSON/JSON_INHERITANCE.md
@@ -191,5 +191,5 @@ Contributors are encouraged to not overuse `copy-from`, as it can decrease the h
 In general, there are two situations where `copy-from` should be used in the core game:
 
 * Two things are nearly identical variants of each other.
-  * If they're pretty much identical (e.g. everything except for their descriptions can be kept, there are only decorative differences, there are no mechanical differences, or in the case of [guns](GUN_NAMING_AND_INCLUSION.md#difference-threshold) minor value differences), they can be handled as [variants](JSON_INFO.md#snippets) (scroll down to the variant example).
+  * If they're pretty much identical (e.g. everything except for their descriptions can be kept, there are only decorative differences, there are no mechanical differences, or in the case of [guns](/doc/GUN_NAMING_AND_INCLUSION.md#difference-threshold) minor value differences), they can be handled as [variants](JSON_INFO.md#snippets) (scroll down to the variant example).
 * A group of entities always (not almost always, always) shares some set of properties, then one or two levels of abstracts can set up a very shallow and narrow hierarchy.
diff --git a/doc/JSON/JSON_LOADING_ORDER.md b/doc/JSON/JSON_LOADING_ORDER.md
@@ -0,0 +1 @@
+../../data/json/LOADING_ORDER.md