Migration (5tcwag) - PasteCode.io

Step 1: Start modifying settings file

2 years ago

Generate the guides.xml

docker run --rm --pull always -v $(pwd):/project -it ghcr.io/typo3-documentation/render-guides:latest migrate Documentation

Step 2: Delete or modify files

2 years ago

Empty your file Includes.rst.txt and add this comment.

.. You can put central messages to display on all pages here

Step 3: Modify guides.xml

2 years ago

Insert this attribute in your extension tag with appropriate name from your composer.json.

interlink-shortcode="my-vendor/my-ext-key"

Step 4: Create files locally

2 years ago

# Create a directory
mkdir -p Documentation-GENERATED-temp

# Execute the Docker container that is provided remotely.
# Renders all files in the `Documentation` and store in `Documentation-GENERATED-temp`.
# On macOS you need to specify the parameter "--user=$(id -u):$(id -g)"
docker run --rm --pull always -v $(pwd):/project -it ghcr.io/typo3-documentation/render-guides:latest --config=Documentation

Step 7: Include tests (Github actions)

2 years ago

Code for ext_key/.github/workflows/test-documentation.yml

name: test documentation  
  
on: [ push, pull_request ]  
  
jobs:  
  tests:  
    name: documentation  
    runs-on: ubuntu-latest  
    steps:  
      - name: Checkout

Step 8: Pre configuration for Makefile

2 years ago

Add these lines to file .editorconfig (phpstorm)

# Makefile  
[{Makefile,**.mk}]  
# Use tabs for indentation (Makefiles require tabs)  
indent_style = tab

Step 9: Makefile

2 years ago

Create the Makefile

.PHONY: help  
help: ## Displays this list of targets with descriptions  
    @echo "The following commands are available:\n"  
    @grep -E '^[a-zA-Z0-9_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[32m%-30s\033[0m %s\n", $$1, $$2}'  
  
.PHONY: docs  
docs: ## Generate projects documentation (from "Documentation" directory)  
    mkdir -p Documentation-GENERATED-temp  
    docker run --rm --pull always -v "$(shell pwd)":/project -t ghcr.io/typo3-documentation/render-guides:latest --config=Documentation

Step 11: Perform make docs

2 years ago

Render documentation locally

make docs