update docs (#555)

* Update doxygen-gh-pages.yml

* reorganise docs folder add ref and a button to switch between dark and light, optimise doxygen

.github/workflows/doxygen-gh-pages.yml

@@ -10,9 +10,27 @@ jobs:
   deploy:
     runs-on: ubuntu-latest
     steps:
-      - uses: DenverCoder1/[email protected]
+      - name: Checkout repository
+        uses: actions/checkout@v3
         with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
+          submodules: "true"
+
+      - name: Install Doxygen
+        run: |
+          sudo apt-get install graphviz doxygen -y
+          wget https://www.doxygen.nl/files/doxygen-1.10.0.linux.bin.tar.gz
+          tar -xzf doxygen-*.linux.bin.tar.gz
+      
+      - name: Generate Doxygen documentation
+        run: |
+          ./doxygen-*/bin/doxygen Doxyfile
+      
+      - name: Create .nojekyll (ensures pages with underscores work on gh pages)
+        run: touch docs/html/.nojekyll
+
+      - name: Deploy to GitHub Pages
+        uses: JamesIves/github-pages-deploy-action@v4
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
           branch: gh-pages
-          folder: docs/html
-          config_file: Doxyfile
+          folder: docs/html

Doxyfile

@@ -483,7 +483,7 @@ TYPEDEF_HIDES_STRUCT   = NO
 # the optimal cache size from a speed point of view.
 # Minimum value: 0, maximum value: 9, default value: 0.
 
-LOOKUP_CACHE_SIZE      = 0
+LOOKUP_CACHE_SIZE      = 1
 
 # The NUM_PROC_THREADS specifies the number of threads doxygen is allowed to use
 # during processing. When set to 0 doxygen will based this on the number of
@@ -496,7 +496,7 @@ LOOKUP_CACHE_SIZE      = 0
 # DOT_NUM_THREADS setting.
 # Minimum value: 0, maximum value: 32, default value: 1.
 
-NUM_PROC_THREADS       = 1
+NUM_PROC_THREADS       = 0
 
 # If the TIMESTAMP tag is set different from NO then each generated page will
 # contain the date or date and time when the page was generated. Setting this to
@@ -946,6 +946,7 @@ WARN_LOGFILE           =
 INPUT                  = docs/ \
                          src/ \
                          include/ \
+                         courses/ \
                          tools/doxygen_syms.md
 
 # This tag can be used to specify the character encoding of the source files
@@ -1095,7 +1096,7 @@ EXAMPLE_RECURSIVE      = NO
 # that contain images that are to be included in the documentation (see the
 # \image command).
 
-IMAGE_PATH             =
+IMAGE_PATH             = docs/images
 
 # The INPUT_FILTER tag can be used to specify a program that doxygen should
 # invoke to filter for each input file. Doxygen will invoke the filter program
@@ -1355,7 +1356,7 @@ HTML_FILE_EXTENSION    = .html
 # of the possible markers and block names see the documentation.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-HTML_HEADER            =
+HTML_HEADER            = docs/header.html
 
 # The HTML_FOOTER tag can be used to specify a user-defined HTML footer for each
 # generated HTML page. If the tag is left blank doxygen will generate a standard
@@ -1396,7 +1397,9 @@ HTML_STYLESHEET        =
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
 HTML_EXTRA_STYLESHEET  = doxygen-awesome-css/doxygen-awesome.css \
-                        doxygen-awesome-css/doxygen-awesome-sidebar-only.css
+                         doxygen-awesome-css/doxygen-awesome-sidebar-only.css \
+                         doxygen-awesome-css/doxygen-awesome-sidebar-only-darkmode-toggle.css \
+                         docs/docs.css
 
 # The HTML_EXTRA_FILES tag can be used to specify one or more extra images or
 # other source files which should be copied to the HTML output directory. Note
@@ -1406,7 +1409,7 @@ HTML_EXTRA_STYLESHEET  = doxygen-awesome-css/doxygen-awesome.css \
 # files will be copied as-is; there are no commands or markers available.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-HTML_EXTRA_FILES       =
+HTML_EXTRA_FILES       = doxygen-awesome-css/doxygen-awesome-darkmode-toggle.js
 
 # The HTML_COLORSTYLE tag can be used to specify if the generated HTML output
 # should be rendered with a dark or light theme.
@@ -1430,15 +1433,15 @@ HTML_COLORSTYLE        = LIGHT
 # Minimum value: 0, maximum value: 359, default value: 220.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-HTML_COLORSTYLE_HUE    = 220
+HTML_COLORSTYLE_HUE    = 209
 
 # The HTML_COLORSTYLE_SAT tag controls the purity (or saturation) of the colors
 # in the HTML output. For a value of 0 the output will use gray-scales only. A
 # value of 255 will produce the most vivid colors.
 # Minimum value: 0, maximum value: 255, default value: 100.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-HTML_COLORSTYLE_SAT    = 100
+HTML_COLORSTYLE_SAT    = 255
 
 # The HTML_COLORSTYLE_GAMMA tag controls the gamma correction applied to the
 # luminance component of the colors in the HTML output. Values below 100
@@ -1449,7 +1452,7 @@ HTML_COLORSTYLE_SAT    = 100
 # Minimum value: 40, maximum value: 240, default value: 80.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-HTML_COLORSTYLE_GAMMA  = 80
+HTML_COLORSTYLE_GAMMA  = 113
 
 # If the HTML_DYNAMIC_MENUS tag is set to YES then the generated HTML
 # documentation will contain a main index with vertical navigation menus that

Makefile

@@ -395,7 +395,9 @@ endif
 
 doc:
 	$(PYTHON) tools/doxygen_symbol_gen.py
-	doxygen
+	doxygen 
+	@$(PRINT) "$(GREEN)Documentation generated in docs/html$(NO_COL)\n"
+	@$(PRINT) "$(GREEN)Results can be viewed by opening docs/html/index.html in a web browser$(NO_COL)\n"
 
 clean:
 	$(RM) -r $(BUILD_DIR)

README.md

@@ -85,7 +85,7 @@ Some menu textures are compressed using a format called tkmk00. A byte-matching
 
 Documentation available online at [https://n64decomp.github.io/mk64/](https://n64decomp.github.io/mk64/).
 
-Documentation generated using [Doxygen](https://www.doxygen.nl/index.html). Run `make doc -j` to test locally. Documentation resides in `docs/html`. Open index.html to view the site.
+Documentation generated using [Doxygen](https://www.doxygen.nl/index.html). Run `make doc` to test locally. Documentation resides in `docs/html`. Open index.html to view the site.
 
 ## Contributing
 

docs/basics/actors.md → docs/actors/actors.md

@@ -1,4 +1,4 @@
-\page actors How Actors Work
+@page actors How Actors Work
 # Actors
 If you are familiar with oot or sm64 prepare to be very disappointed. Both games split actors into separate files. In an unorderly fashion, mk64 appears to place all actors in the same file save for the odd exception.
 

docs/actors/items.md

@@ -0,0 +1 @@
+@page items Items

docs/actors/objects.md

@@ -0,0 +1,2 @@
+@page objects Objects
+# Objects

docs/basics/vehicles.md → docs/actors/vehicles.md

@@ -1,4 +1,4 @@
-\page vehicles Vehicles
+@page vehicles Vehicles
 
 [TOC]
 

docs/basics/actorsmenu.md → docs/actorsmenu.md

@@ -1,105 +1,24 @@
-\page actorsmenu Actors
+@page actorsmenu Actors
 
 Actors are dynamic game objects usually subject to game physics such as gravity, force, and collision. They might move around the map, spin, or interactive in some manner. Alternatively, static game objects cannot move and cannot be interacted with. They can use collision but not physics. A course model and Mario Raceway's Pipe are examples of static objects. Any of the items or player karts are examples of dynamic game objects; actors.  
 
 mk64 contains two systems for implementing actors. They have been deemed as actors and objects, albeit an explicit or categorical difference between the two has yet to be determined. The running theory is that the systems were designed by different developers that were perhaps not communicating resulting in game objects being randomly distributed between the two.  
 
 The two main variables to concern yourself with are `gActorList` and `gObjectList`; the core containers of the two systems.  
 
-`gActorList` contains:
+@ref gActorList contains:
 ```
 trees, bushes, falling rocks, kiwano-fruit, banana, shells, piranha-plant, train wheels, rail-road crossing, cows, yoshi-valley's egg, spinning signs, palm trees, paddle for the paddle-wheeled boat, wheels for cars/trucks, etc.
 ```
 The actor code has two main parts; the update code and the render code. The update code alters the position/rotation of the object whereas the render code displays the object on the screen.  
 
-`gObjectList` contains:
+@ref gObjectList contains:
 ```
 thwomps, bowser fire-breath, moles, hedgehogs, snowmen, crabs, particles, leaves, etc (also, probably penguins and birds).
 ```
 The object system is much more complex than actors and is not well documented.
-
-\htmlonly
+@htmlonly
 <br>
-<style>
-.pagebutton {
-    display: inline-block;
-    margin-right: 1em;
-    margin-bottom: 1em;
-}
-.pagelink {
-    display: block;
-    background-color: rgb(40, 44, 52);
-    width: 320px;
-    box-shadow: 0 0 0 0;
-    transition: 0.3s ease;
-}
-.pagelink:hover {
-  box-shadow: 0 5px 15px 5px rgba(0,0,0,1);
-
-}
-.pagelink:hover img {
-  transform: scale3d(1.1,1.1,1.1);
-
-}
-.pageimg {
-    display: inline-block;
-    width: 100%;
-    position: relative;
-    overflow: hidden;
-}
-.pageimg img {
-    transition: 0.3s ease;
-}
-.content {
-    color: white;
-    font-size: 1em;
-    padding: 0;
-    margin: 0;
-}
-.pageheading {
-    padding: .5em .5em;
-    font-size: 18px;
-    color: white;
-    font-weight: bold;
-    text-decoration: none;
-}
-.pagedescription {
-    color: #fff;
-    border-color: transparent;
-    opacity: 0.75;
-    height: 84px;
-    text-overflow: ellipsis;
-    overflow: hidden;
-    margin-top: 10px;
-    display: block;
-    padding: 10px;
-    text-decoration: none;
-    line-height: 1.64em;
-    font-size: 1em;
-    font-weight: normal;
-    text-decoration: none;
-}
-.pagea {
-    display: inline-block;
-}
-.pagea:link {
-    text-decoration: none;
-}
-.pagea:visited {
-    text-decoration: none;
-}
-.pagea:hover {
-    text-decoration: none;
-}
-.pagea:active {
-    text-decoration: none;
-}
-p {
-    margin: 0;
-    padding: 0;
-}
-</style>
-
 <div class="pagebutton">
 <a class="pagea" href="actors.html">
 <div class="pagelink">
@@ -156,9 +75,9 @@ p {
 </a>
 </div>
 
-\endhtmlonly
+@endhtmlonly
 
-\subpage actors
-\subpage objects
-\subpage vehicles
-\subpage items
+@subpage actors
+@subpage objects
+@subpage vehicles
+@subpage items

docs/basics/BUILD_WINDOWS.md

@@ -1,4 +1,4 @@
-\page buildwindows Compiling for Windows
+@page buildwindows Compiling for Windows
 ## Compiling mk64 Decomp In Windows
 
 ***This method is not recommended nor supported. However, it is the only solution to build in W7/W8. WSL is the path of least resistance, use that not this***

docs/basics/basicconcepts.md

@@ -14,15 +14,15 @@ Computers use addresses to jump through code. This works similar to a house numb
 A typical N64 address: `0x80160158`
 
 In an N64 program, addresses begin at `0x80000000`. As you create code, data, and the like, the compiler will add onto this base number and assign variables to an address.
-```
+```c
 s32 a = 2; // 0x80000004
 s32 b = 7; // 0x80000008
 s32 c = 5; // 0x8000000C
 s32 d = 1; // 0x80000010
 s32 e = 3; // 0x80000014
 ```
 Replacing a variable with a hard-coded address grabs the value at that address.
-```
+```c
 print(0x80000004); // or
 print(a);
 ```
@@ -40,7 +40,7 @@ Texture a_texture[] = {
 };
 ```
 The address of this could extend from `0x80000100` to `0x800000534`. However, you would not see data begin at `0x80000533`. The compiler generally aligns objects to 4, 8, 0xC, or 0x10. With the exception being when you're working with s16 and s8. If you have:
-```
+```c
 s16 a = 3; // Value compiled to 0x0003
 s32 b = 5; // Value compiled to 0x00000005
 ```
@@ -52,7 +52,7 @@ The compiler aligned `b` to the nearest 0x4. If there were two s16's then the bl
 
 # How Errors Happen
 The maximum value of an s8 (0x00) is 0xFF or 255. `0xFF + 1 = 0x100` imagine this scenario:
-```
+```c
 s8 a = 1;
 s8 b = 2;
 s8 c = 3;

docs/basics/compiling.md

@@ -11,13 +11,13 @@ The build system has the following package requirements:
 To add submodules run `git submodule update --init --recursive` after cloning.
 
 # Linux
-```
+```bash
 sudo apt install build-essential pkg-config git binutils-mips-linux-gnu python3 zlib1g-dev libaudiofile-dev libcapstone-dev
 ```
 
 ### Arch
 
-```
+```bash
 sudo pacman -S base-devel capstone python
 ```
 Install the following AUR package:
@@ -34,7 +34,7 @@ Not recommended. Use WSL unless this is your only option.
 # macOS
 
 Install [Homebrew](https://brew.sh), then install the following dependencies:
-```
+```bash
 brew update
 brew install python3 capstone coreutils make pkg-config tehzz/n64-dev/mips64-elf-binutils
 ```
@@ -44,19 +44,19 @@ Build using `gmake` ensuring homebrew `make` is used instead of the old macOS sy
 # Docker
 
 Build the Docker image:
-```
+```bash
 docker build -t mk64 .
 ```
 
 When building and using other tools, append the following in front of every command you run:
 ```bash
-docker run --rm -v ${PWD}:/mk64 mk64
+docker run --rm -v .:/mk64 mk64
 ```
 
 For example:
 ```bash
-docker run --rm -v ${PWD}:/mk64 mk64 make -C tools
-docker run --rm -v ${PWD}:/mk64 mk64 make
+docker run --rm -v .:/mk64 mk64 make -C tools
+docker run --rm -v .:/mk64 mk64 make
 ```
 
 # Building US
@@ -78,16 +78,16 @@ mk64 decomp supports two EU versions
 * EU 1.1 `eu-final`
 
 Build using
-```
+```bash
 make -j VERSION=eu-1.0
 ```
 or
-```
+```bash
 make -j VERSION=eu-final
 ```
 
 First-diff/diff commands for EU
-```
+```bash
 python3 first-diff.py --eu
 ./diff <function> -eu
 ```