Convert docs/ folder to mdBook (#4684)

* Convert docs/ folder to mdBook

* INSTALL.md Markdown fixes (also affects GitHub web)

* Don't try to rewrite bare links in HTML attributes

* lowercase anchors in fix_links.py

.github/workflows/docs.yml

@@ -0,0 +1,37 @@
+name: Docs
+on:
+  push:
+    branches:
+      - master
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pages: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Install latest mdbook
+        run: |
+          tag=$(curl 'https://api.github.com/repos/rust-lang/mdbook/releases/latest' | jq -r '.tag_name')
+          url="https://github.com/rust-lang/mdbook/releases/download/${tag}/mdbook-${tag}-x86_64-unknown-linux-gnu.tar.gz"
+          mkdir mdbook
+          curl -sSL $url | tar -xz --directory=./mdbook
+          echo `pwd`/mdbook >> $GITHUB_PATH
+      - name: Build Book
+        run: |
+          cd docs
+          mdbook build
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: 'docs/book'
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

INSTALL.md

@@ -215,9 +215,9 @@ Note that in msys2, Copy is Ctrl+Insert and Paste is Shift+Insert.
 
 To install Python on msys2, simply run the following commands:
 
-    ```bash
+```bash
-    pacman -S mingw-w64-x86_64-python3
+pacman -S mingw-w64-x86_64-python3
-    ```
+```
 
 Python is now installed.
 
@@ -592,7 +592,8 @@ Note that this is not necessary for a non-modern (agbcc) build since those are b
 
 <details>
     <summary><i>Deprecated; installing agbcc is optional since 1.7.0</i>.</summary>
-2. Install agbcc into pokeemerald-expansion. The commands to run depend on certain conditions. **You should only follow one of the listed instructions**:
+
+1. Install agbcc into pokeemerald-expansion. The commands to run depend on certain conditions. **You should only follow one of the listed instructions**:
 - If agbcc has **not been built before** in the folder where you chose to store pokeemerald Expansion, run the following commands to build and install it into pokeemerald-expansion:
 
     ```bash
@@ -621,18 +622,20 @@ Note that this is not necessary for a non-modern (agbcc) build since those are b
     <details>
         <summary><i>Note...</i></summary>
 
-        > If building agbcc or pokeemerald results in an error, try deleting the agbcc folder and re-installing agbcc as if it has not been built before.
+    > If building agbcc or pokeemerald results in an error, try deleting the agbcc folder and re-installing agbcc as if it has not been built before.
     </details>
 
-3. Once agbcc is installed, change directory back to the base directory where pokeemerald-expansion and agbcc are stored:
+2. Once agbcc is installed, change directory back to the base directory where pokeemerald-expansion and agbcc are stored:
 
     ```bash
     cd ..
     ```
-    
-4. To compile with agbcc:
 
-    ```make agbcc```
+3. To compile with agbcc:
+
+    ```bash
+    make agbcc
+    ```
 
 </details>
 

README.md

@@ -14,11 +14,11 @@ Based off RHH's pokeemerald-expansion v1.8.0 https://github.com/rh-hideout/pokee
 
 ## What features are included?
 - ***IMPORTANT*❗❗ Read through these to learn what features you can toggle**:
-    - [Battle configurations](include/config/battle.h)
+    - [Battle configurations](https://github.com/rh-hideout/pokeemerald-expansion/blob/master/include/config/battle.h)
-    - [Pokémon configurations](include/config/pokemon.h)
+    - [Pokémon configurations](https://github.com/rh-hideout/pokeemerald-expansion/blob/master/include/config/pokemon.h)
-    - [Item configurations](include/config/item.h)
+    - [Item configurations](https://github.com/rh-hideout/pokeemerald-expansion/blob/master/include/config/item.h)
-    - [Overworld configurations](include/config/overworld.h)
+    - [Overworld configurations](https://github.com/rh-hideout/pokeemerald-expansion/blob/master/include/config/overworld.h)
-    - [Debug configurations](include/config/debug.h)
+    - [Debug configurations](https://github.com/rh-hideout/pokeemerald-expansion/blob/master/include/config/debug.h)
 - ***Upgraded battle engine.***
     - Gen5+ damage calculation.
     - 2v2 Wild battles support.
@@ -62,7 +62,7 @@ Based off RHH's pokeemerald-expansion v1.8.0 https://github.com/rh-hideout/pokee
     - Recalculating stats at the end of every battle.
     - Level 100 Pokémon can earn EVs.
     - Inverse battle support.
-    - TONS of other features listed [here](include/config/battle.h).
+    - TONS of other features listed [here](https://github.com/rh-hideout/pokeemerald-expansion/blob/master/include/config/battle.h).
 - ***Full Trainer customization***
     - Nickname, EVs, IVs, moves, ability, ball, friendship, nature, gender, shininess.
     - Custom tag battle support (teaming up an NPC in a double battle).
@@ -94,7 +94,7 @@ Based off RHH's pokeemerald-expansion v1.8.0 https://github.com/rh-hideout/pokee
     - All gender differences.
         - Custom female icons for female Hippopotas Hippowdon, Pikachu and Wobbufett
     - 3 Perfect IVs on Legendaries, Mythicals and Ultra Beasts.
-- ***Customizable form change tables. Full list of methods [here](include/constants/form_change_types.h).***
+- ***Customizable form change tables. Full list of methods [here](https://github.com/rh-hideout/pokeemerald-expansion/blob/master/include/constants/form_change_types.h).***
     - Item holding (eg. Giratina/Arceus)
     - Item using (eg. Oricorio)
         - Time of day option for Shaymin
@@ -115,7 +115,7 @@ Based off RHH's pokeemerald-expansion v1.8.0 https://github.com/rh-hideout/pokee
     - Egg Move Transfer, including Mirror Herb (configurable).
     - Nature inheriting 100% of the time with Everstone (configurable)
     - Gen6+ Ability inheriting (configurable).
-- ***Items from newer Generations. Full list [here](include/constants/items.h).***
+- ***Items from newer Generations. Full list [here](https://github.com/rh-hideout/pokeemerald-expansion/blob/master/include/constants/items.h).***
     - ***Gen 6+ Exp. Share*** (configurable)
     - Berserk Gene
     - Most battle items from Gen 4+

docs/.gitignore

@@ -0,0 +1 @@
+book

docs/CHANGELOG.md

@@ -0,0 +1 @@
+../CHANGELOG.md

docs/INSTALL.md

@@ -0,0 +1 @@
+../INSTALL.md

docs/README.md

@@ -0,0 +1 @@
+../README.md

docs/SUMMARY.md

@@ -0,0 +1,52 @@
+# Summary
+
+- [README](./README.md)
+- [Installation](./INSTALL.md)
+    - [Setting up WSL1 (Legacy Portion)](./legacy_WSL1_INSTALL.md)
+- [Changelog](./CHANGELOG.md)
+    - [1.8.x]()
+        - [Version 1.8.4](changelogs/1.8.x/1.8.4.md)
+        - [Version 1.8.3](changelogs/1.8.x/1.8.3.md)
+        - [Version 1.8.2](changelogs/1.8.x/1.8.2.md)
+        - [Version 1.8.1](changelogs/1.8.x/1.8.1.md)
+        - [Version 1.8.0](changelogs/1.8.x/1.8.0.md)
+
+    - [1.7.x]()
+        - [Version 1.7.4](changelogs/1.7.x/1.7.4.md)
+        - [Version 1.7.3](changelogs/1.7.x/1.7.3.md)
+        - [Version 1.7.2](changelogs/1.7.x/1.7.2.md)
+        - [Version 1.7.1](changelogs/1.7.x/1.7.1.md)
+        - [Version 1.7.0](changelogs/1.7.x/1.7.0.md)
+
+    - [1.6.x]()
+        - [Version 1.6.2](changelogs/1.6.x/1.6.2.md)
+        - [Version 1.6.1](changelogs/1.6.x/1.6.1.md)
+        - [Version 1.6.0](changelogs/1.6.x/1.6.0.md)
+
+    - [1.5.x]()
+        - [Version 1.5.3](changelogs/1.5.x/1.5.3.md)
+        - [Version 1.5.2](changelogs/1.5.x/1.5.2.md)
+        - [Version 1.5.1](changelogs/1.5.x/1.5.1.md)
+        - [Version 1.5.0](changelogs/1.5.x/1.5.0.md)
+
+    - [1.4.x]()
+        - [Version 1.4.3](changelogs/1.4.x/1.4.3.md)
+        - [Version 1.4.2](changelogs/1.4.x/1.4.2.md)
+        - [Version 1.4.1](changelogs/1.4.x/1.4.1.md)
+        - [Version 1.4.0](changelogs/1.4.x/1.4.0.md)
+
+    - [1.3.x]()
+        - [Version 1.3.0](changelogs/1.3.x/1.3.0.md)
+
+    - [1.2.x]()
+        - [Version 1.2.0](changelogs/1.2.x/1.2.0.md)
+
+    - [1.1.x]()
+        - [Version 1.1.1](changelogs/1.1.x/1.1.1.md)
+        - [Version 1.1.0](changelogs/1.1.x/1.1.0.md)
+
+    - [1.0.x]()
+        - [Version 1.0.0](changelogs/1.0.x/1.0.0.md)
+
+    - [Pre-1.0.x]()
+        - [Version 0.9.0](changelogs/0.9.x/0.9.0.md)

docs/book.toml

@@ -0,0 +1,13 @@
+[book]
+language = "en"
+multilingual = false
+src = "."
+title = "pokeemerald-expansion"
+
+[output.html]
+git-repository-url = "https://github.com/rh-hideout/pokeemerald-expansion"
+edit-url-template = "https://github.com/rh-hideout/pokeemerald-expansion/edit/master/docs/{path}"
+site-url = "/pokeemerald-expansion/"
+
+[preprocessor.fix_links]
+command = "python3 fix_links.py"

docs/fix_links.py

@@ -0,0 +1,51 @@
+# workarounds to avoid changing current directory structure
+# autolink logic based on https://github.com/zopieux/py-gfm/blob/fd7b33ed138d240d24dfb659acff7d4ce3f43745/gfm/autolink.py
+
+import json
+import sys
+import re
+
+URL_RE = re.compile(
+    r"(```(?s:.)+?```|`.+?`|<.+?>)|"
+    r"\b((?:(?i:ftp|https?)://|(?i:www)\d{0,3}[.])(?:[^\s()<>]+|"
+    r"\(([^\s()<>]+|(\([^\s()<>]+\)))*\))+(?:\(([^\s()<>]+|(\([^\s()"
+    r"<>]+\)))*\)|[^\s`!()\[\]{};:" + r"'" + r'".,<>?«»“”‘’*]))'
+)
+PROTOCOL_RE = re.compile(r"^(?i:ftp|https?)://")
+
+ANCHOR_RE = re.compile(r"(\]\((?:[^)#]+\.md)?#)([^)]+\))")
+
+def handle_url(m):
+    code = m.group(1)
+    if code:
+        return code
+    href = m.group(2)
+    if not PROTOCOL_RE.match(href):
+        href = "http://%s" % href
+    return f'<{href}>'
+
+def handle_anchor(m):
+    page = m.group(1)
+    anchor = m.group(2)
+    return page + anchor.lower()
+
+def proc_items(items):
+    for item in items:
+        if 'Chapter' in item:
+            s = item['Chapter']['content']
+            s = s.replace('](README.md)', '](./)')
+            s = s.replace('](/INSTALL.md', '](INSTALL.md')
+            s = s.replace('](docs/', '](')
+            item['Chapter']['content'] = URL_RE.sub(handle_url, s)
+            item['Chapter']['content'] = ANCHOR_RE.sub(handle_anchor, s)
+            proc_items(item['Chapter']['sub_items'])
+
+if __name__ == '__main__':
+    if len(sys.argv) > 1:
+        if sys.argv[1] == "supports":
+            sys.exit(0)
+
+    context, book = json.load(sys.stdin)
+    proc_items(book['sections'])
+
+    print(json.dumps(book))

docs/legacy_WSL1_INSTALL.md

@@ -38,4 +38,4 @@
     source /etc/profile.d/devkit-env.sh
     ```
 
-Proceed to [Choosing where to store pokeemerald (WSL1) of the current INSTALL.md](/INSTALL.md#choosing-where-to-store-pokeemerald-WSL1).
+Proceed to [Choosing where to store pokeemerald (WSL1) of the current INSTALL.md](/INSTALL.md#choosing-where-to-store-pokeemerald-expansion-WSL1).