Doc: Create mkdocs-based documentation

Also adds CMake code to build and install the documentation
into our ZIP packages.

CMake files now get a fancy license header.

Author: modeco80

.github/workflows/autobuild.yml

@@ -7,16 +7,19 @@ on: [ push, pull_request ]
 #    branches: [ master ]
 #  workflow_dispatch:
 
+# todo: maybe a job to update and push to gh-pages branch
+#   if a commit modifies files in docs/ or /mkdocs.yml
+
 jobs:
   build:
     runs-on: ubuntu-latest
 
     steps:
       - uses: actions/checkout@v2
 
-      # This techinically also "Installs" it too.
+      # This techinically also "Installs" ps2sdk too.
       # TODO: CACHE THIS SO I DON'T KEEP HITTING GITHUB SERVERS.
-      - name: Fetch and setup ps2sdk
+      - name: Fetch and setup dependencies
         run: |
           export PS2DEV=$HOME/ps2dev
           export PS2SDK=$PS2DEV/ps2sdk
@@ -31,15 +34,18 @@ jobs:
           echo "PS2DEV=$PS2DEV" >> $GITHUB_ENV
           echo "PS2SDK=$PS2SDK" >> $GITHUB_ENV
           echo "GSKIT=$GSKIT" >> $GITHUB_ENV
+          pip install mkdocs
 
       - name: Build elfldr (release) and package
         run: |
           cmake -B build -DCMAKE_TOOLCHAIN_FILE=cmake/Toolchain/ps2.cmake -DCMAKE_BUILD_TYPE=Release
+          cmake --build build -t docs
           cmake --build build -t package
 
       - name: Build elfldr (debug) and package
         run: |
           cmake -B build_debug -DCMAKE_TOOLCHAIN_FILE=cmake/Toolchain/ps2.cmake -DCMAKE_BUILD_TYPE=Debug
+          cmake --build build -t docs
           cmake --build build_debug -t package
 
       - name: Upload elfldr artifacts (release)

.gitignore

@@ -3,3 +3,4 @@ build/
 cmake-build-*
 
 /publish.sh
+/site

CMakeLists.txt

@@ -1,3 +1,10 @@
+#
+# SSX-Elfldr
+#
+# (C) 2021-2022 Lily/modeco80 <[email protected]>
+# under the terms of the MIT license.
+#
+
 cmake_minimum_required(VERSION 3.19)
 
 ##if(NOT CMAKE_SYSTEM_NAME STREQUAL "Playstation2")
@@ -13,7 +20,8 @@ if(" ${CMAKE_SOURCE_DIR}" STREQUAL " ${CMAKE_BINARY_DIR}")
     message(FATAL_ERROR "In-source-tree builds are strictly prohibited. Please don't do them.")
 endif()
 
-include(${CMAKE_SOURCE_DIR}/cmake/Policies.cmake)
+include(cmake/CMakeNewPolicy.cmake)
+
 project(elfldr
         LANGUAGES CXX
         DESCRIPTION "HostFS enabling Mod/ELF loader for the SSX games on PS2"
@@ -34,6 +42,9 @@ add_custom_target(__elfldr_gittag
         SOURCES ${PROJECT_BINARY_DIR}/Version.h)
 set_source_files_properties(${PROJECT_BINARY_DIR}/Version.h PROPERTIES GENERATED TRUE)
 
+# ElfLdr mkdocs
+include(MkDocs)
+
 # Include elfldr modules
 add_subdirectory(src/runtime)
 add_subdirectory(src/utils)
@@ -50,12 +61,20 @@ add_subdirectory(src/sampleerl)
 set(CMAKE_INSTALL_PREFIX /)
 set(CPACK_SET_DESTDIR ON)
 
-install(TARGETS elfldr)
-
 # documentation
-install(FILES ${PROJECT_SOURCE_DIR}/README.md ${PROJECT_SOURCE_DIR}/LICENSE DESTINATION ${CMAKE_INSTALL_PREFIX})
+install(FILES ${PROJECT_SOURCE_DIR}/README.md ${PROJECT_SOURCE_DIR}/LICENSE DESTINATION /)
+
+# Install static mkdocs documentation
+# if documentation build is enabled
+if(MkDocs_FOUND)
+    install(DIRECTORY ${PROJECT_SOURCE_DIR}/site/ DESTINATION /doc)
+endif()
+
 # todo: mkdocs generated page in /doc
 
+install(TARGETS elfldr)
+
+
 ## CPack (used by GitHub Actions to package releases)
 
 if(NOT DEFINED CPACK_GENERATOR)

README.md

@@ -4,109 +4,12 @@ A patching game loader for the SSX games on PS2, providing the ability to run th
 
 It also provides a general patching/function hooking framework for mod developers to use.
 
-## Game Support Table
-
-Note that game regions/versions or whole games that are marked as Unsupported are planned to be supported later in development..
-
-| Game          | Region/Version      | Support Status |
-|---------------|---------------------|----------------|
-| SSX OG (2000) | USA (1.0)           | ✅              |
-| SSX OG (2000) | USA (Greatest Hits) | ❓              |
-| SSX OG (2000) | PAL (1.0)           | ❌              |
-| SSX OG (2000) | NTSC-J (1.0)        | ❌              |
-| SSX Tricky    | USA (1.0)           | ✅              |
-| SSX Tricky    | PAL/NTSC-J          | ❌              |
-| SSX 3         | OPSM2 Demo          | 🧩️            |
-| SSX 3         | KR Demo             | 🧩             |
-| SSX 3         | PAL/NTSC-J          | ❌              |
-| SSX On Tour   | (N/A)               | ❌              |
-
-#### Legend
-
-| Symbol | Definition             |
-|--------|------------------------|
-| ✅️     | Supported              |
-| 🧩️    | Partial/In development |
-| ❌️     | Unsupported            |
-| ❓      | Unknown                |
+## Documentation
+ 
+See the /docs directory for documentation, or the /doc directory in a release package.
 
 ## Releases
 
 Stable releases are available [at the Releases tab](https://github.com/SSXModding/SSX-ElfLdr/releases).
 
-Automatic unstable builds of Elfldr are available [via Github Actions](https://github.com/SSXModding/SSX-ElfLdr/actions).
-
-
-## Setup
-
-**NOTE:** A graphical setup program which automatically handles ISO/physical disc extraction will be provided soon.
-
-For now:
-
-- Follow the game specific instructions first (they are below this initial step).
-- Copy `bin/elfldr.elf` from the release .zip file alongside the main game ELF in the directory you chose.
-- In PCSX2:
-    - Enable HostFS by checking "System->Game Settings->Enable Host Filesystem".
-    - File->Run ELF the `elfldr.elf` file for the game you extracted.
-    - Enjoy your ElfLdr-enhanced game!
-
-### SSX OG
-
-- Extract the game's files from the ISO or physical disk into a directory of your choosing.
-- Using a .BIG extraction tool of your choice, extract the .BIG archives in `data/models`.
-    - Once done, copy the files from the newly-made `data/models` to the actual `data/models` directory.
-
-### SSX Tricky
-
-- Extract the game's files from the ISO or physical disk into a directory of your choosing.
-- Using a .BIG extraction tool of your choice, extract the .BIG archives in `data/models`.
-    - Once done, copy the files from the newly-made `data/models` to the actual `data/models` directory.
-
-### SSX 3
-
-- Extract the game's files from the ISO or physical disk into a directory of your choosing.
-- (Up to you) Remove the two .PAD files, they are not needed by the game.
-
-## Patch Descriptions
-
-### HostFS Patch
-
-This patch allows the game to load files entirely from a folder on your computer.
-
-This makes it easier for modders to tinker with the game.
-
-It also makes it easier for players to install mods.
-
-It finally also solves legality issues as mods no longer need to be distributed as the full game.
-
-### MemClr patch
-
-This patch disables the memory clear pattern the SSX games do, which is a byproduct of some debugging code left in from
-the REAL (REwritten EA Library?) library's custom memory allocator.
-
-### Experimental patch
-
-This patch is mostly a dumping ground for very untested code, and as of right now serves as an ERL loader.
-
-It also registers the heap allocator used by elfldr (for now).
-
-## Building from source
-
-You need PS2SDK installed (the PS2DEV/open source one, not the Sony one).
-
-It can be gathered [here](https://github.com/ps2dev/ps2toolchain) if you do not have it installed.
-
-To build:
-
-```bash
-$ cmake -B build -GNinja -DCMAKE_TOOLCHAIN_FILE=cmake/toolchain/ps2.cmake
-$ cmake --build build
-# Profit? (elfldr.elf in build/)
-```
-
-Generating a package
-
-```bash
-$ cmake --build build -t package
-# check build/packages for the generated zip file
-```
+Automatic unstable builds of Elfldr are available [via GitHub Actions](https://github.com/SSXModding/SSX-ElfLdr/actions).

cmake/Policies.cmake cmake/CMakeNewPolicy.cmakecmake/Policies.cmake renamed to cmake/CMakeNewPolicy.cmake

@@ -1,3 +1,10 @@
+#
+# SSX-Elfldr
+#
+# (C) 2021-2022 Lily/modeco80 <[email protected]>
+# under the terms of the MIT license.
+#
+
 # CMake policy configuration
 
 if(POLICY CMP0026)

cmake/FindMkDocs.cmake

@@ -0,0 +1,40 @@
+#.rst:
+# FindMkDocs
+# -----------
+#
+# This module looks for MkDocs and is based on the FindDoxygen module
+#
+# MkDocs is a static site generator that's geared towards building project documentation.
+# http://www.mkdocs.org
+#
+# This modules defines the following variables:
+#
+# ::
+#
+#    MKDOCS_EXECUTABLE     = The path to the MkDocs command.
+#    MKDOCS_FOUND          = Was MkDocs found or not?
+#    MKDOCS_VERSION        = The version reported by mkdocs --version
+#
+
+#
+# Find MkDocs...
+#
+
+find_program(MKDOCS_EXECUTABLE
+        NAMES mkdocs
+        PATHS
+            /usr/bin
+            /usr/local/bin
+            $ENV{HOME}/.local/bin
+        DOC "MkDocs documentation generation tool (http://www.mkdocs.org)"
+        )
+
+if(MKDOCS_EXECUTABLE)
+    execute_process(COMMAND ${MKDOCS_EXECUTABLE} "--version" OUTPUT_VARIABLE MKDOCS_VERSION_OUTPUT OUTPUT_STRIP_TRAILING_WHITESPACE)
+    string(REGEX MATCH "[0-9*]\.*" MKDOCS_VERSION ${MKDOCS_VERSION_OUTPUT})
+endif()
+
+include(FindPackageHandleStandardArgs)
+find_package_handle_standard_args(MkDocs DEFAULT_MSG MKDOCS_EXECUTABLE MKDOCS_VERSION)
+
+mark_as_advanced(MKDOCS_EXECUTABLE)

cmake/GitTag.cmake

@@ -1,5 +1,12 @@
 #!/usr/bin/cmake -P
 
+#
+# SSX-Elfldr
+#
+# (C) 2021-2022 Lily/modeco80 <[email protected]>
+# under the terms of the MIT license.
+#
+
 #
 # Headless script to generate git versioning with only cmake installed
 #

cmake/MkDocs.cmake

@@ -0,0 +1,20 @@
+#
+# SSX-Elfldr
+#
+# (C) 2021-2022 Lily/modeco80 <[email protected]>
+# under the terms of the MIT license.
+#
+
+# Semi-hack to build documentation.
+
+find_package(MkDocs)
+
+if(MkDocs_FOUND)
+    set(DOCS_ENABLED TRUE)
+    message(STATUS "Enabling documentation build")
+    add_custom_target(docs ALL ${MKDOCS_EXECUTABLE} build
+            WORKING_DIRECTORY ..
+            COMMENT "Generating HTML documentation" VERBATIM)
+else()
+    set(DOCS_ENABLED FALSE)
+endif()

cmake/Toolchain/Platform/Playstation2.cmake

@@ -1,3 +1,10 @@
+#
+# SSX-Elfldr
+#
+# (C) 2021-2022 Lily/modeco80 <[email protected]>
+# under the terms of the MIT license.
+#
+
 # CMake platform settings for PlayStation 2
 
 set(CMAKE_EXECUTABLE_SUFFIX ".elf")

cmake/Toolchain/ps2.cmake

@@ -1,3 +1,10 @@
+#
+# SSX-Elfldr
+#
+# (C) 2021-2022 Lily/modeco80 <[email protected]>
+# under the terms of the MIT license.
+#
+
 # Based off the shipped ps2dev.cmake toolchain file
 # in the ps2sdk source tree, modified for elfldr
 
@@ -9,6 +16,7 @@ set(CMAKE_SYSTEM_PROCESSOR "mips64r5900el")
 # our PlayStation2 platform. Otherwise, CMake will yell
 # and complain (rightfully.)
 list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_LIST_DIR}")
+list(APPEND CMAKE_MODULE_PATH "${PROJECT_SOURCE_DIR}/cmake")
 
 set(CMAKE_C_COMPILER mips64r5900el-ps2-elf-gcc)
 set(CMAKE_CXX_COMPILER mips64r5900el-ps2-elf-g++)