Transform to modern sphinx framework

.github/workflows/deploy.yml

@@ -0,0 +1,25 @@
+name: Deploy Sphinx documentation
+
+on:
+  push:
+    branches: [master]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Install dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y python3 python3-pip
+          pip install -r requirements.txt
+      - name: Build documentation
+        working-directory: docs
+        run: make html
+      - name: Deploy to GitHub Pages
+        uses: actions/deploy-pages@v1
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          source: "docs/_build/html"
+          branch: gh-pages

.gitignore

@@ -1,2 +1,6 @@
 node_modules
 _book
+
+# Sphinx
+.venv
+_build

.vscode/settings.json

@@ -0,0 +1,6 @@
+{
+    "yaml.schemas": {
+        "https://squidfunk.github.io/mkdocs-material/schema.json": "mkdocs.yml",
+        "https://json.schemastore.org/github-workflow.json": "file:///c%3A/Users/Dennis/Projects/itch-docs/.github/workflows/deploy.yml"
+    }
+}

README.md

@@ -1,5 +1,7 @@
 # The itch book
 
+<!-- start add-to-docs -->
+
 This book is a living documentation for [the itch.io app](https://itch.io/app).
 
 Its intended audience includes:
@@ -13,16 +15,10 @@ Its intended audience includes:
 If you find a typo, a factual inaccuracy, or an important caveat not covered in  
 this book, feel free to submit a pull request to the [GitHub repository](https://github.com/itchio/itch-docs).
 
+<!-- end add-to-docs -->
 
-## Note to developer
-
-This book is build using the opensource
-[Gitbook](https://github.com/GitbookIO/gitbook-cli) tool. Sadly it's abandoned
-so building this file currently involves a little patch. See
-`release/ci-book.js`
-
-If you about to change something about the build process, make a new tag and
-push that first so we have a backup of the compiled output incase we need to
-roll back quickly. Tagged releases are pushed to separate folder on the docs
-bucket.
+## Note to developers
 
+This documentation is built using [Sphinx](https://github.com/sphinx-doc/sphinx) which is using python.
+Activate a virtual environment with `.venv/Scripts/activate` and install the dependencies with `pip install -r requirements.txt`.
+Creating the compiled output then is as simple as running `make html` in the `docs` directory.

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

appendix/README.md → docs/appendix/README.md

@@ -7,5 +7,9 @@ While this book is focused on the itch app, we felt like some subjects slightly
 * [Acknowledgements](./acknowledgements.md)
 * [Building Linux software into a prefix](./building-into-a-prefix.md)
 
+```{toctree}
+:hidden:
 
-
+acknowledgements
+building-into-a-prefix
+```

docs/conf.py

@@ -0,0 +1,41 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = "Itch.io App"
+copyright = (
+    "2024, Amos Wenger, leafo and the community on GitHub"
+)
+author = "Amos Wenger, leafo and the community on GitHub"
+release = "0.1"
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = ["myst_parser", "sphinx_tippy", "sphinx.ext.githubpages"]
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "furo"
+html_static_path = ["_static"]
+html_title = "Itch.io App"
+
+html_theme_options = {
+    "light_css_variables": {
+        "color-brand-primary": "#8E3737",
+        "color-brand-content": "#8E3737",
+    },
+    "dark_css_variables": {
+        "color-brand-primary": "#ea4d4d",
+        "color-brand-content": "#ea4d4d",
+    },
+}

developing/README.md → docs/developing/README.md

@@ -1,5 +1,11 @@
-
 # Contributor guide
 
 Since itch is open-source, and we maintain it actively, anyone can contribute
 to it in various ways! This chapter describes how.
+
+```{toctree}
+:hidden:
+
+help
+behind-the-scenes
+```

developing/behind-the-scenes.md → docs/developing/behind-the-scenes.md

@@ -2,3 +2,9 @@
 
 This section describes a few things that are done behind the curtain so that the app can function. You don't need to learn about them to use the app or contribute to it, but it's cool to have somewhere canonical where it's documented.
 
+```{toctree}
+:hidden:
+
+continuous-deployment
+../using/installing/dependencies
+```

developing/data-flow.md → docs/developing/data-flow.md

@@ -1,3 +1,8 @@
+---
+orphan: true
+---
+# Data Flow
+
 itch follows the [Redux](http://redux.js.org/index.html) design pattern — to understand the rest of this page,  
 you need to be familiar with it. The basics are as follows:
 
@@ -91,6 +96,3 @@ interact with |                     ||                    | render to
                                     ||    things that cross it are JSON
                                     ||    payloads sent asynchronously via IPC
 ```
-
-
-

developing/diego.md → docs/developing/diego.md

@@ -1,11 +1,13 @@
-
+---
+orphan: true
+---
 # diego
 
 diego is our diagnostics mercenary: it attempts to dump information about the
 Operating System, CPU and Graphics Card to a log file when someone tries to
 install a game.
 
-You can [read its source](../app/util/diego.js), or look at these example outputs
+You can read its source (`app/util/diego.js`), or look at these example outputs
 
 
 ## Example outputs

developing/environment-variables.md → docs/developing/environment-variables.md

@@ -1,3 +1,5 @@
+# Environment Variables
+
 These environment variables will change the behavior of the app:
 
 * `DEVTOOLS=1` — start with Chromium Devtools open — useful when something goes
@@ -12,4 +14,3 @@ These environment variables will change the behavior of the app:
 * `ITCH_EMULATE_OFFLINE=1` - simulate a network outage. This only affects itch, not butler.
 
 See the [Performance hacking](/developing/performance.md) section for other environment variables that impact the app.
-

developing/getting-started.md → docs/developing/getting-started.md

@@ -1,12 +1,14 @@
-## Setting up itch for development
+# Setting up itch for development
 
 itch is built in TypeScript and runs inside of Electron.
 
 To get started, install the latest [node.js](https://nodejs.org/)
 
-> Linux distributions tend to ship outdated node.js versions
->
-> Use the nodesource [binary distributions](https://github.com/nodesource/distributions/) to get an up-to-date one.
+```{caution}
+Linux distributions tend to ship outdated node.js versions
+
+Use the nodesource [binary distributions](https://github.com/nodesource/distributions/) to get an up-to-date one.
+```
 
 Then, clone the [https://github.com/itchio/itch](https://github.com/itchio/itch) repository somewhere.
 
@@ -16,7 +18,9 @@ Install the javascript dependencies by running this command from within the `itc
 $ npm install
 ```
 
-> For native modules, you'll need a compiler toolchain: Visual Studio 2015 on Windows, gcc/clang on Linux/macOS. See the [node-gyp](https://github.com/nodejs/node-gyp) page for more information on this.
+```{note}
+For native modules, you'll need a compiler toolchain: Visual Studio 2015 on Windows, gcc/clang on Linux/macOS. See the [node-gyp](https://github.com/nodejs/node-gyp) page for more information on this.
+```
 
 Finally, start the app!
 
@@ -179,4 +183,3 @@ We check the quality of the app's code by two kinds of tests:
 * [Integration Tests](integration-tests.md), which test interactions
 
 Check out the pages linked above to learn more about what their purpose is, when and how they're run, and how they're written.
-

developing/help.md → docs/developing/help.md

@@ -1,5 +1,15 @@
 # What you can do to help
 
+```{toctree}
+:hidden:
+
+getting-started
+unit-tests
+integration-tests
+environment-variables
+performance
+```
+
 If you like our work and want to help us make it even better, here are things you can do.
 
 ## Test games with the app

developing/integration-tests.md → docs/developing/integration-tests.md

@@ -8,7 +8,7 @@ They make sure that all of the code, together, makes meaningful interactions hap
 
 The app is tested as a whole using a homegrown golang runner that speaks webdriver to the app.
 
-### Running integration tests
+## Running integration tests
 
 It looks deceptively simple:
 
@@ -22,14 +22,11 @@ If you're an itch.io employee, poke Amos about it to get set up. If you're not,
 
 We'll take care of that part!
 
-### Writing an integration test
+## Writing an integration test
 
 Scenarios live in `integration-tests`, along with some support code that makes it all tick. They're also explicitly listed in `integration-tests/main.go`.
 
 These resources can be useful:
 
 * The [webdriver API docs](http://webdriver.io/api.html)
 * Existing tests!
-
-
-

developing/performance.md → docs/developing/performance.md

@@ -67,4 +67,3 @@ export GoodComponent extends React.PureComponent<any, any> {
 ```
 
 More details in [this medium article](https://medium.com/@esamatti/react-js-pure-render-performance-anti-pattern-fb88c101332f)
-

developing/unit-tests.md → docs/developing/unit-tests.md

@@ -1,4 +1,3 @@
-
 # Unit tests
 
 Unit tests are for checking that a specific, well-isolated bit of code does what

docs/index.md

@@ -0,0 +1,19 @@
+---
+hide-toc: true
+---
+
+# Itch.io App Documentation
+
+```{include} ../README.md
+:start-after: <!-- start add-to-docs -->
+:end-before: <!-- end add-to-docs -->
+```
+
+```{toctree}
+:hidden:
+
+using/README.md
+integrating/README.md
+developing/README
+appendix/README.md
+```