Merge pull request #286 from markusweigelt/replace-sphinx

Replace Sphinx with new Typo3 documentation variant

.github/workflows/documentation.yml

@@ -0,0 +1,17 @@
+name: test documentation
+
+on: [ push, pull_request ]
+
+jobs:
+    tests:
+        name: documentation
+        runs-on: ubuntu-latest
+        steps:
+            - name: Checkout
+              uses: actions/checkout@v4
+
+            - name: Test if the documentation will render without warnings
+              run: |
+                  mkdir -p Documentation-GENERATED-temp \
+                  && docker run --rm --pull always -v $(pwd):/project \
+                     ghcr.io/typo3-documentation/render-guides:latest --config=Documentation --no-progress --fail-on-log

DEVELOPMENT.md

@@ -16,35 +16,59 @@ npm run build
 
 ## Documentation
 
-### Local Preview Server
+Build the DFG-Viewer documentation using the `docs:build` script with Composer.
+This script generates the documentation using the rendering tool for Typo3 and
+places it in the `Documentation-GENERATED-temp` folder.
 
-To preview the rendered output and automatically rebuild documentation on changes, you may spawn a local server. This supports auto-refresh and is faster than the official preview build, but omits some features such as syntax highlighting.
+```bash
+composer docs:build
+```
+
+Take a look at the documentation by opening the file `Index.html` in the folder
+`Documentation-GENERATED-temp` in your browser.
+
+### Provide via Http Server (optional)
 
-This requires Python 2 to be installed.
+Starts the http server and mounts the mandatory directory `Documentation-GENERATED-temp`.
 
 ```bash
-# First start: Setup Sphinx in a virtualenv
-composer docs:setup
+composer docs:start
+```
+
+Take a look at the documentation by opening <http://localhost:8000>
+in your browser.
+
+The server runs in detached mode, so you will need to stop the http server manually.
 
-# Spawn server
-composer docs:serve
-composer docs:serve -- -E  # Don't use a saved environment (useful when changing toctree)
-composer docs:serve -- -p 8000  # Port may be specified
+```bash
+composer docs:stop
 ```
 
-By default, the output is served to http://127.0.0.1:8000.
+### Troubleshooting
+
+#### Permission
 
-### Official Preview Build
+The documentation container runs as a non-root user. If there are some problem regarding
+the permission of container user you can link the UID and GID of host into the container
+using the `--user` parameter.
 
-Build documentation using the [official Docker image](https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/RenderingDocs/Quickstart.html):
+**Example:**
 
 ```bash
-# Full build
-composer docs:t3 makehtml
+docker run --rm --user=$(id -u):$(id -g) [...]
+```
+
+_In the `docs:build` Composer script, this parameter is already included.
+If any issues arise, you can adjust or remove it as needed._
 
-# Only run sphinx-build
-composer docs:t3 just1sphinxbuild
+#### Output directory
 
-# (Alternative) Run docker-compose manually
-docker-compose -f ./Build/Documentation/docker-compose.t3docs.yml run --rm t3docs makehtml
+The default documentation directory name is `Documentation-GENERATED-temp`.
+If you want to change the directory name add the `--output` parameter at the
+end of the building command.
+
+**Example:**
+
+```bash
+[...] --config ./Documentation --output="My_Documentation_Directory"
 ```

Documentation/guides.xml

@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<guides xmlns="https://www.phpdoc.org/guides" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="https://www.phpdoc.org/guides ../vendor/phpdocumentor/guides-cli/resources/schema/guides.xsd" links-are-relative="true">
+  <extension class="\T3Docs\Typo3DocsTheme\DependencyInjection\Typo3DocsThemeExtension" project-home="https://github.com/slub/dfg-viewer" project-contact="mailto:typo3@slub-dresden.de" project-repository="https://github.com/slub/dfg-viewer" project-issues="https://github.com/slub/dfg-viewer/issues" edit-on-github-branch="master" edit-on-github="slub/dfg-viewer" typo3-core-preferred="stable"/>
+  <project title="DFG-Viewer" release="6.0.0" copyright="2020 by the author"/>
+</guides>

composer.json

@@ -52,9 +52,18 @@
     }
   },
   "scripts": {
-    "docs:setup": "./Build/Documentation/sphinx.sh install",
-    "docs:serve": "./Build/Documentation/sphinx.sh serve",
-    "docs:t3": "docker-compose -f ./Build/Documentation/docker-compose.t3docs.yml run --rm t3docs"
+    "docs:build": [
+      "rm -Rf ./Documentation-GENERATED-temp",
+      "docker run --user=$(id -u):$(id -g) --rm -v ./:/project -it ghcr.io/typo3-documentation/render-guides:latest --config ./Documentation",
+      "cp ./Build/Documentation/index.html ./Documentation-GENERATED-temp"
+    ],
+    "docs:start": "docker run -d --name dfgviewer_docs --rm -v ./Documentation-GENERATED-temp:/serve -p 8000:8000 jdkelley/simple-http-server:latest",
+    "docs:stop": "docker stop dfgviewer_docs",
+    "docs:rebuild": [
+      "@composer docs:stop",
+      "@composer docs:build",
+      "@composer docs:start"
+    ]
   },
   "config": {
     "allow-plugins": {