[MAINTENANCE] Replace Sphinx with new Typo3 documentation variant (#1213

)

Co-authored-by: Sebastian Meyer <[email protected]>

.github/workflows/documentation.yml

@@ -0,0 +1,17 @@
+name: Build 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 warning
+              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

@@ -124,50 +124,68 @@ docker-compose down
 
 ## Documentation
 
-Following TYPO3's practices, the main documentation of the extension is located in `Documentation` and written in [reStructuredText](https://en.wikipedia.org/wiki/ReStructuredText). The build system is [Sphinx](https://en.wikipedia.org/wiki/Sphinx_(documentation_generator)).
+Build the 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.
 
-### Local Preview Server
+```bash
+composer docs:build
+```
 
-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.
+Take a look at the documentation by opening the file `Index.html` in the folder
+`Documentation-GENERATED-temp` in your browser.
 
-This requires Python 2 to be installed.
+### Provide via HTTP Server (optional)
 
-```bash
-# First start: Setup Sphinx in a virtualenv
-composer docs:setup
+Starts the HTTP server and mounts the mandatory directory `Documentation-GENERATED-temp`.
 
-# 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:start
 ```
 
-By default, the output is served to http://127.0.0.1:8000.
+Take a look at the documentation by opening <http://localhost:8000>
+in your browser.
 
-> The setup and serve commands are defined in [Build/Documentation/sphinx.sh](./Build/Documentation/sphinx.sh).
+The server runs in detached mode, so you will need to stop it manually.
 
-### Official Preview Build
+```bash
+composer docs:stop
+```
 
-The TYPO3 project [provides a Docker image to build documentation](https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/RenderingDocs/Quickstart.html). This requires both Docker and Docker Compose to be installed.
+### Database Documentation
+
+Generate the database reference table:
 
 ```bash
-# Full build
-composer docs:t3 makehtml
+composer install
+composer docs:db
+```
+
+### Troubleshooting
+
+#### Permission
 
-# Only run sphinx-build
-composer docs:t3 just1sphinxbuild
+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.
 
-# (Alternative) Run docker-compose manually
-docker-compose -f ./Build/Documentation/docker-compose.t3docs.yml run --rm t3docs makehtml
+**Example:**
+
+```bash
+docker run --rm --user=$(id -u):$(id -g) [...]
 ```
 
-The build output is available at [Documentation-GENERATED-temp/Result/project/0.0.0/Index.html](./Documentation-GENERATED-temp/Result/project/0.0.0/Index.html).
+_In the `docs:build` Composer script, this parameter is already included.
+If any issues arise, you can adjust or remove it as needed._
 
-### Database Documentation
+#### Output directory
 
-Generate the database reference table:
+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
-composer install
-composer docs:db
+[...] --config ./Documentation --output="My_Documentation_Directory"
 ```

Documentation/Configuration/Index.rst

@@ -77,7 +77,7 @@ This is not the desired behaviour. You should disable
 requested page instead. The caching will be disabled in this case. This was
 the default behaviour before TYPO3 6.x.
 
-.. figure:: ../Images/Configuration/New\ TYPO3\ site\ \[TYPO3\ CMS\ 9.5.26\ .png
+.. figure:: ../Images/Configuration/New_TYPO3_site.png
    :width: 820px
    :alt: TYPO3 Configuration of pageNotFoundOnCHashError in Install Tool
 

Documentation/Developers/Metadata.rst

@@ -17,32 +17,38 @@ Data format records, which are stored on the root page (PID = 0), tell Kitodo ho
 A record contains the following fields:
 
 .. t3-field-list-table::
-   :header-rows:  1
-
-   - :---: Make description column three times the width of field column.
-     :field,1:       Field
-     :description,3: Description
-
-   - :field:         Format Name
-     :description:   Name of the type that is used to reference it.
-
-                     -  For metadata embedded via ``<mdWrap>``, this corresponds to its ``MDTYPE`` or ``OTHERMDTYPE`` attribute.
-
-                     -  For XML fulltext files, this corresponds to the capitalized root tag of the file.
-
-   - :field:         Root Element
-     :description:   The XML root element used by this format. In METS, this is used to locate the sub-root within an ``<mdWrap>``.
-
-   - :field:         Namespace URI
-     :description:   The XML namespace URI used by this format. It is registered within the parser and may be used to declare namespace prefixes.
-
-   - :field:         Class Name
-     :description:   (Optional) Fully qualified name of the PHP class that handles the format. Some formats are pre-defined in the ``Kitodo\Dlf\Format`` namespace.
-
-                     For metadata, this is used to programmatically extract values by implementing ``MetadataInterface``.
-                     This may be useful, for example, when the value is needed universally, is difficult to extract via XPath, or requires post-processing.
-
-                     For fulltext, this is used to parse the fulltext file by implementing the ``FulltextInterface``.
+ :header-rows: 1
+
+ - :field,1:
+      Field
+   :description,3:
+      Description
+ - :field:
+      Format Name
+   :description:
+      Name of the type that is used to reference it.
+
+      For metadata embedded via ``<mdWrap>``, this corresponds to its ``MDTYPE`` or ``OTHERMDTYPE`` attribute.
+
+      For XML fulltext files, this corresponds to the capitalized root tag of the file.
+ - :field:
+      Root Element
+   :description:
+      The XML root element used by this format. In METS, this is used to locate the sub-root within an ``<mdWrap>``.
+ - :field:
+      Namespace URI
+   :description:
+      The XML namespace URI used by this format. It is registered within the parser and may be used to declare namespace prefixes.
+
+ - :field:
+      Class Name
+   :description:
+      (Optional) Fully qualified name of the PHP class that handles the format. Some formats are pre-defined in the ``Kitodo\Dlf\Format`` namespace.
+
+      For metadata, this is used to programmatically extract values by implementing ``MetadataInterface``.
+      This may be useful, for example, when the value is needed universally, is difficult to extract via XPath, or requires post-processing.
+
+      For fulltext, this is used to parse the fulltext file by implementing the ``FulltextInterface``.
 
 
 TypoScript Wrap

Documentation/Introduction/Index.rst

@@ -109,31 +109,31 @@ Some examples of Kitodo.Presentation in action on the `Digital Collection of SLU
 
 http://digital.slub-dresden.de/id457052678
 
-.. figure:: ../Images/Introduction/Digitale\ Sammlungen\ \ Colloquia\ Lutheri\ conscripta\ a\ quibusdam\ et\ alia\ quaedam\ addita\ sunt.\ Thesaurus\ theologiae\ -\ Mscr.Dresd.A.180.d.png
+.. figure:: ../Images/Introduction/Digitale_Sammlungen_Colloquia_Lutheri.png
    :width: 820px
    :alt: Mscr.Dresd.A.180.d
 
    Mscr.Dresd.A.180.d
 
 http://digital.slub-dresden.de/id416971482-19060601
 
-.. figure:: ../Images/Introduction/Digitale\ Sammlungen\ \ The\ Daily\ record\ and\ the\ Dresden\ daily\ \ \ 01.06.1906.png
+.. figure:: ../Images/Introduction/Digitale_Sammlungen_The_Daily_1906.png
    :width: 820px
    :alt: Newspaper issue with full-text switched on
 
    Newspaper Issue with Full-text Switched on
 
 http://digital.slub-dresden.de/id501434038
 
-.. figure:: ../Images/Introduction/Digitale\ Sammlungen\ \ Dresdner\ Nachrichten.png
+.. figure:: ../Images/Introduction/Digitale_Sammlungen_Dresdner_Nachrichten.png
    :width: 820px
    :alt: All Years Overview of a Newspaper Title
 
    All Years Overview of a Newspaper Title
 
 http://digital.slub-dresden.de/id501434038-1942
 
-.. figure:: ../Images/Introduction/Digitale\ Sammlungen\ \ Dresdner\ Nachrichten\ \ \ 1942.png
+.. figure:: ../Images/Introduction/Digitale_Sammlungen_Dresdner_Nachrichten_1942.png
    :width: 820px
    :alt: Calendar View of a Newspaper Year