From d9045f52e0dfb70e3e8b5147a75234486a51cfd0 Mon Sep 17 00:00:00 2001 From: "lina.wolf" Date: Wed, 28 Feb 2024 14:27:29 +0100 Subject: [PATCH 1/6] [TASK] Switch to PHP-based rendering --- Documentation/Includes.rst.txt | 35 +------------------ Documentation/Settings.cfg | 64 ---------------------------------- Documentation/guides.xml | 21 +++++++++++ Makefile | 11 ++++++ 4 files changed, 33 insertions(+), 98 deletions(-) delete mode 100644 Documentation/Settings.cfg create mode 100644 Documentation/guides.xml create mode 100644 Makefile diff --git a/Documentation/Includes.rst.txt b/Documentation/Includes.rst.txt index 85827642..23625074 100644 --- a/Documentation/Includes.rst.txt +++ b/Documentation/Includes.rst.txt @@ -1,34 +1 @@ -.. More information about this file: - https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/GeneralConventions/FileStructure.html#includes-rst-txt - -.. ---------- -.. text roles -.. ---------- - -.. role:: aspect(emphasis) -.. role:: bash(code) -.. role:: html(code) -.. role:: js(code) -.. role:: php(code) -.. role:: rst(code) -.. role:: sep(strong) -.. role:: sql(code) - -.. role:: tsconfig(code) - :class: typoscript - -.. role:: typoscript(code) -.. role:: xml(code) - :class: html - -.. role:: yaml(code) - -.. default-role:: code - -.. --------- -.. highlight -.. --------- - -.. By default, code blocks use TypoScript syntax highlighting - -.. highlight:: typoscript +.. You can put central messages to display on all pages here diff --git a/Documentation/Settings.cfg b/Documentation/Settings.cfg deleted file mode 100644 index e46048dc..00000000 --- a/Documentation/Settings.cfg +++ /dev/null @@ -1,64 +0,0 @@ -# More information about this file: -# https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/GeneralConventions/FileStructure.html#settings-cfg - -[general] - -project = TSconfig Reference -version = main (development) -release = main (development) -copyright = since 2012 by the TYPO3 contributors - -[html_theme_options] - -# "Edit on GitHub" button -github_repository = TYPO3-Documentation/TYPO3CMS-Reference-TSconfig -github_branch = main - -# Footer links -project_home = https://docs.typo3.org/m/typo3/reference-tsconfig/main/en-us/ -project_contact = https://typo3.slack.com/archives/C028JEPJL -project_repository = https://github.com/TYPO3-Documentation/TYPO3CMS-Reference-TSconfig -project_issues = https://github.com/TYPO3-Documentation/TYPO3CMS-Reference-TSconfig/issues -project_discussions = - -use_opensearch = - -[intersphinx_mapping] - -# Official TYPO3 manuals -h2document = https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/ -# t3content = https://docs.typo3.org/m/typo3/guide-contentandmarketing/main/en-us/ -# t3contribute = https://docs.typo3.org/m/typo3/guide-contributionworkflow/main/en-us/ -t3coreapi = https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ -# t3editors = https://docs.typo3.org/m/typo3/tutorial-editors/main/en-us/ -# t3extexample = https://docs.typo3.org/m/typo3/guide-example-extension-manual/main/en-us/ -# t3home = https://docs.typo3.org/ -t3sitepackage = https://docs.typo3.org/m/typo3/tutorial-sitepackage/main/en-us/ -# t3start = https://docs.typo3.org/m/typo3/tutorial-getting-started/main/en-us/ -t3tca = https://docs.typo3.org/m/typo3/reference-tca/main/en-us/ -# t3translate = https://docs.typo3.org/m/typo3/guide-frontendlocalization/main/en-us/ -# t3tsconfig = https://docs.typo3.org/m/typo3/reference-tsconfig/main/en-us/ -t3tsref = https://docs.typo3.org/m/typo3/reference-typoscript/main/en-us/ -t3ts45 = https://docs.typo3.org/m/typo3/tutorial-typoscript-in-45-minutes/main/en-us/ -# t3viewhelper = https://docs.typo3.org/other/typo3/view-helper-reference/main/en-us/ -# t3upgrade = https://docs.typo3.org/m/typo3/guide-installation/main/en-us/ - -# TYPO3 system extensions -ext_adminpanel = https://docs.typo3.org/c/typo3/cms-adminpanel/main/en-us/ -ext_core = https://docs.typo3.org/c/typo3/cms-core/main/en-us/ -# ext_dashboard = https://docs.typo3.org/c/typo3/cms-dashboard/main/en-us/ -# ext_felogin = https://docs.typo3.org/c/typo3/cms-felogin/main/en-us/ -# ext_form = https://docs.typo3.org/c/typo3/cms-form/main/en-us/ -# ext_fsc = https://docs.typo3.org/c/typo3/cms-fluid-styled-content/main/en-us/ -# ext_impexp = https://docs.typo3.org/c/typo3/cms-impexp/main/en-us/ -# ext_indexed_search = https://docs.typo3.org/c/typo3/cms-indexed-search/main/en-us/ -# ext_linkvalidator = https://docs.typo3.org/c/typo3/cms-linkvalidator/main/en-us/ -ext_lowlevel = https://docs.typo3.org/c/typo3/cms-lowlevel/main/en-us/ -# ext_reactions = https://docs.typo3.org/c/typo3/cms-reactions/main/en-us/ -# ext_recycler = https://docs.typo3.org/c/typo3/cms-recycler/main/en-us/ -# ext_redirects = https://docs.typo3.org/c/typo3/cms-redirects/main/en-us/ -# ext_reports = https://docs.typo3.org/c/typo3/cms-reports/main/en-us/ -ext_rte_ckeditor = https://docs.typo3.org/c/typo3/cms-rte-ckeditor/main/en-us/ -# ext_scheduler = https://docs.typo3.org/c/typo3/cms-scheduler/main/en-us/ -# ext_seo = https://docs.typo3.org/c/typo3/cms-seo/main/en-us/ -# ext_workspaces = https://docs.typo3.org/c/typo3/cms-workspaces/main/en-us/ diff --git a/Documentation/guides.xml b/Documentation/guides.xml new file mode 100644 index 00000000..5f81d956 --- /dev/null +++ b/Documentation/guides.xml @@ -0,0 +1,21 @@ + + + + + + diff --git a/Makefile b/Makefile new file mode 100644 index 00000000..325b94fd --- /dev/null +++ b/Makefile @@ -0,0 +1,11 @@ +.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 docs (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 From 0a84c65000a780b9f92eb358ea60e8f6b3aa5432 Mon Sep 17 00:00:00 2001 From: "lina.wolf" Date: Thu, 29 Feb 2024 05:42:19 +0100 Subject: [PATCH 2/6] [TASK] Use new Parser for Rest Checks Move testing to Make file --- .ddev/config.yaml | 2 +- .github/workflows/documentation.yml | 17 +++ .github/workflows/tests.yml | 3 - Build/Scripts/runTests.sh | 8 -- Build/Scripts/validateRstFiles.php | 183 ---------------------------- Makefile | 20 ++- 6 files changed, 37 insertions(+), 196 deletions(-) create mode 100644 .github/workflows/documentation.yml delete mode 100755 Build/Scripts/validateRstFiles.php diff --git a/.ddev/config.yaml b/.ddev/config.yaml index 4d9dec3c..9c2fdc77 100644 --- a/.ddev/config.yaml +++ b/.ddev/config.yaml @@ -1,7 +1,7 @@ name: reference-tsconfig type: php docroot: "" -php_version: "8.1" +php_version: "8.2" webserver_type: nginx-fpm router_http_port: "8081" router_https_port: "4434" diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml new file mode 100644 index 00000000..79ac662e --- /dev/null +++ b/.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 diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index 0859ddd6..c7b37058 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -22,6 +22,3 @@ jobs: - name: CGL run: Build/Scripts/runTests.sh -n -p ${{ env.php }} -s cgl -n - - - name: Check Rst - run: Build/Scripts/runTests.sh -p ${{ env.php }} -s checkRst diff --git a/Build/Scripts/runTests.sh b/Build/Scripts/runTests.sh index 93d9a47f..5c161e04 100755 --- a/Build/Scripts/runTests.sh +++ b/Build/Scripts/runTests.sh @@ -42,11 +42,9 @@ No arguments: Run all checks with PHP 8.2 Options: -s <...> Specifies which test suite to run - - checkRst: test .rst files for integrity - cgl: cgl test and fix all php files - composerUpdate: "composer update", handy if host has no PHP - lint: PHP linting - - rector: Apply Rector rules -p <8.2|8.3> Specifies the PHP minor version to be used @@ -165,12 +163,6 @@ DOCKER_PHP_IMAGE=`echo "php${PHP_VERSION}" | sed -e 's/\.//'` # Suite execution case ${TEST_SUITE} in - checkRst) - setUpDockerComposeDotEnv - docker-compose run check_rst - SUITE_EXIT_CODE=$? - docker-compose down - ;; cgl) # Active dry-run for cgl needs not "-n" but specific options if [[ ! -z ${CGLCHECK_DRY_RUN} ]]; then diff --git a/Build/Scripts/validateRstFiles.php b/Build/Scripts/validateRstFiles.php deleted file mode 100755 index ceb80938..00000000 --- a/Build/Scripts/validateRstFiles.php +++ /dev/null @@ -1,183 +0,0 @@ -#!/usr/bin/env php - - * - * By default, the standard path is used. You can override this for - * testing purposes. - */ -class validateRstFiles -{ - /** - * @var array - */ - protected $messages; - - /** - * @var bool - */ - protected $isError; - - /** - * @var string - */ - protected $baseDir = 'Documentation'; - - public function __construct(string $dir = '') - { - if ($dir) { - $this->baseDir = $dir; - } - } - - public function validate() - { - printf('Searching for rst snippets in ' . $this->baseDir . chr(10)); - - $count = 0; - $finder = $this->findFiles(); - foreach ($finder as $file) { - $filename = (string)$file; - $this->clearMessages(); - $fileContent = $file->getContents(); - $this->validateContent($fileContent); - - if ($this->isError) { - $shortPath = substr($filename, strlen($this->baseDir)); - $shortPath = ltrim($shortPath, '/\\'); - $count++; - printf( - '%-10s | %-12s | %-17s | %s ' . chr(10), - $this->messages['include']['title'], - $this->messages['reference']['title'], - $this->messages['index']['title'], - $shortPath - ); - if ($this->messages['include']['message']) { - printf($this->messages['include']['message'] . chr(10)); - } - if ($this->messages['reference']['message']) { - printf($this->messages['reference']['message'] . chr(10)); - } - if ($this->messages['index']['message']) { - printf($this->messages['index']['message'] . chr(10)); - } - } - } - - if ($count > 0) { - fwrite(STDERR, 'Found ' . $count . ' rst files with errors, check full log for details.' . chr(10)); - exit(1); - } - exit(0); - } - - public function findFiles(): Finder - { - $finder = new Finder(); - $finder - ->files() - ->in($this->baseDir) - ->name('/\.rst$/'); - - return $finder; - } - - protected function clearMessages() - { - $this->messages = [ - 'include' => [ - 'title' => '', - 'message' => '', - ], - 'reference' => [ - 'title' => '', - 'message' => '', - ], - 'index' => [ - 'title' => '', - 'message' => '', - ], - ]; - - $this->isError = false; - } - - protected function validateContent(string $fileContent) - { - $checkForRequired = [ - [ - 'type' => 'include', - 'regex' => '#^\\.\\.\s+include::\s+\/Includes.rst.txt|\:orphan\:#m', - 'title' => 'no include', - 'message' => 'insert \'.. include:: /Includes.rst.txt\' in first line of the file', - ], - [ - 'type' => 'include', - 'regex' => '#\={2,}\n.*\n\={2,}#m', - 'title' => 'no title', - 'message' => 'Each document must have a title with multiple === above and below', - ], - ]; - - foreach ($checkForRequired as $values) { - if (preg_match($values['regex'], $fileContent) !== 1) { - $this->messages[$values['type']]['title'] = $values['title']; - $this->messages[$values['type']]['message'] = $values['message']; - $this->isError = true; - } - } - - $checkForForbidden = [ - [ - 'type' => 'include', - 'regex' => '#\.\. *important::#m', - 'title' => 'admonition warning forbidden', - 'message' => 'use ".. attention" instead of ".. important"', - ], - ]; - - foreach ($checkForForbidden as $values) { - if (preg_match($values['regex'], $fileContent) > 0) { - $this->messages[$values['type']]['title'] = $values['title']; - $this->messages[$values['type']]['message'] = $values['message']; - $this->isError = true; - } - } - } -} - -$dir = ''; -$args = getopt('d:'); -if (isset($args['d'])) { - $dir = $args['d']; -} -$validator = new validateRstFiles($dir); -$validator->validate(); diff --git a/Makefile b/Makefile index 325b94fd..1196ff05 100644 --- a/Makefile +++ b/Makefile @@ -3,9 +3,27 @@ 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 docs (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 + +.PHONY: codesnippets +codesnippets: ## Regenerate automatic code snippets + .Build/vendor/bin/typo3 codesnippet:create Documentation/CodeSnippets/ + +.PHONY: test +test: test-lint test-cgl test-docs ## Runs all test suites + +.PHONY: test-lint +test-lint: ## Lint PHP includes + Build/Scripts/runTests.sh -s lint + +.PHONY: test-cgl +test-cgl: ## Test coding guidelines to PHP includes + Build/Scripts/runTests.sh -n -s cgl + +.PHONY: fix-cgl +fix-cgl: ## Apply coding guidelines to PHP includes + Build/Scripts/runTests.sh -s cgl From 0c494eb83defe80a8b54ad2bacc7ab6ac873213a Mon Sep 17 00:00:00 2001 From: "lina.wolf" Date: Thu, 29 Feb 2024 08:22:44 +0100 Subject: [PATCH 3/6] [TASK] Use automaticly configured interlink repos --- Documentation/guides.xml | 1 - 1 file changed, 1 deletion(-) diff --git a/Documentation/guides.xml b/Documentation/guides.xml index 5f81d956..178cebb5 100644 --- a/Documentation/guides.xml +++ b/Documentation/guides.xml @@ -17,5 +17,4 @@ version="main (development)" copyright="since 2012 by the TYPO3 contributors" /> - From 8fdf46bdc6aee4e1823a2e381ed2802d7732f70e Mon Sep 17 00:00:00 2001 From: "lina.wolf" Date: Thu, 29 Feb 2024 08:30:14 +0100 Subject: [PATCH 4/6] [TASK] Remove superfluous index --- Documentation/Index.rst | 1 - Documentation/genindex.rst | 7 ------- 2 files changed, 8 deletions(-) delete mode 100644 Documentation/genindex.rst diff --git a/Documentation/Index.rst b/Documentation/Index.rst index 420e6d58..ac87516f 100644 --- a/Documentation/Index.rst +++ b/Documentation/Index.rst @@ -53,4 +53,3 @@ Explained. :hidden: Sitemap - genindex diff --git a/Documentation/genindex.rst b/Documentation/genindex.rst deleted file mode 100644 index 806ec56a..00000000 --- a/Documentation/genindex.rst +++ /dev/null @@ -1,7 +0,0 @@ -.. include:: /Includes.rst.txt - -===== -Index -===== - -.. Sphinx will insert here the general index automatically. From c27ba677fa4602032b6ae07f296fb362a1e73a21 Mon Sep 17 00:00:00 2001 From: "lina.wolf" Date: Thu, 29 Feb 2024 10:13:02 +0100 Subject: [PATCH 5/6] [TASK] Remove rst tests from composer.json --- composer.json | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/composer.json b/composer.json index d3422e17..eaf18012 100644 --- a/composer.json +++ b/composer.json @@ -63,8 +63,7 @@ }, "scripts": { "check": [ - "@check:php", - "@check:rst" + "@check:php" ], "check:php": [ "@check:php:lint", @@ -72,7 +71,6 @@ ], "check:php:cs": "Build/Scripts/runTests.sh -n -s cgl", "check:php:lint": "Build/Scripts/runTests.sh -s lint", - "check:rst": "Build/Scripts/runTests.sh -s checkRst", "fix": [ "@fix:php" ], From 97af21f76952370debac13fefd01d18da9edab06 Mon Sep 17 00:00:00 2001 From: "lina.wolf" Date: Thu, 29 Feb 2024 11:22:43 +0100 Subject: [PATCH 6/6] [TASK] Remove composer scripts again --- composer.json | 24 ------------------------ 1 file changed, 24 deletions(-) diff --git a/composer.json b/composer.json index eaf18012..4e0ddd7e 100644 --- a/composer.json +++ b/composer.json @@ -60,29 +60,5 @@ "typo3/cms-tstemplate": "dev-main", "typo3/cms-viewpage": "dev-main", "typo3/cms-workspaces": "dev-main" - }, - "scripts": { - "check": [ - "@check:php" - ], - "check:php": [ - "@check:php:lint", - "@check:php:cs" - ], - "check:php:cs": "Build/Scripts/runTests.sh -n -s cgl", - "check:php:lint": "Build/Scripts/runTests.sh -s lint", - "fix": [ - "@fix:php" - ], - "fix:php": [ - "@fix:php:cs" - ], - "fix:php:cs": "Build/Scripts/runTests.sh -s cgl", - "generate:codesnippets": [ - ".Build/vendor/bin/typo3 codesnippet:create Documentation/CodeSnippets/" - ], - "generate": [ - "@generate:codesnippets" - ] } }