From 639d1f7fdbff90429394b6c2b044dd464ad2e059 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Elias=20H=C3=A4u=C3=9Fler?= Date: Tue, 15 Oct 2024 11:13:27 +0200 Subject: [PATCH] [TASK] Switch documentation to PHP-based rendering --- .github/workflows/cgl.yaml | 6 +++++ .../Configuration/ExtensionConfiguration.rst | 10 +------- Documentation/Contributing/Index.rst | 23 +++++++++-------- Documentation/DeveloperCorner/Caching.rst | 8 +++--- Documentation/DeveloperCorner/Formatters.rst | 4 +-- Documentation/DeveloperCorner/Middlewares.rst | 25 +++++++------------ .../DeveloperCorner/SolutionProviders.rst | 10 ++++---- Documentation/Includes.rst.txt | 18 +------------ Documentation/Index.rst | 1 - Documentation/Settings.cfg | 17 ------------- Documentation/Usage/ConsoleCommands.rst | 9 ------- Documentation/Usage/ExceptionHandler.rst | 2 +- Documentation/genindex.rst | 7 ------ Documentation/guides.xml | 19 ++++++++++++++ composer.json | 4 +-- docker-compose.yml | 11 ++++---- version-bumper.yaml | 4 +-- 17 files changed, 69 insertions(+), 109 deletions(-) delete mode 100644 Documentation/Settings.cfg delete mode 100644 Documentation/genindex.rst create mode 100644 Documentation/guides.xml diff --git a/.github/workflows/cgl.yaml b/.github/workflows/cgl.yaml index f03aad92..693f4908 100644 --- a/.github/workflows/cgl.yaml +++ b/.github/workflows/cgl.yaml @@ -81,3 +81,9 @@ jobs: # Migration - name: Rector migration run: composer cgl migration:rector -- --dry-run + + # Documentation + - name: Check documentation build + run: | + mkdir -p .build/docs + composer docs:build -- --no-progress --fail-on-log diff --git a/Documentation/Configuration/ExtensionConfiguration.rst b/Documentation/Configuration/ExtensionConfiguration.rst index 249fada8..5b150202 100644 --- a/Documentation/Configuration/ExtensionConfiguration.rst +++ b/Documentation/Configuration/ExtensionConfiguration.rst @@ -11,7 +11,6 @@ The extension currently provides the following configuration options: .. _extconf-provider: .. confval:: provider - :type: string (FQCN) :Default: :php:class:`EliasHaeussler\\Typo3Solver\\ProblemSolving\\Solution\\Provider\\OpenAISolutionProvider` @@ -25,7 +24,7 @@ The extension currently provides the following configuration options: .. _extconf-prompt: .. confval:: prompt - + :name: extconf-prompt :type: string (FQCN) :Default: :php:class:`EliasHaeussler\\Typo3Solver\\ProblemSolving\\Solution\\Prompt\\DefaultPrompt` @@ -39,7 +38,6 @@ The extension currently provides the following configuration options: .. _extconf-ignoredCodes: .. confval:: ignoredCodes - :type: string (comma-separated list) Comma-separated list of exception codes to ignore during problem solving. @@ -54,7 +52,6 @@ The extension currently provides the following configuration options: .. _extconf-api-key: .. confval:: api.key - :type: string :ref:`API key ` for OpenAI requests. @@ -67,7 +64,6 @@ The extension currently provides the following configuration options: .. _extconf-attributes-model: .. confval:: attributes.model - :type: string :Default: `gpt-3.5-turbo-0301` @@ -78,7 +74,6 @@ The extension currently provides the following configuration options: .. _extconf-attributes-maxTokens: .. confval:: attributes.maxTokens - :type: integer :Default: `300` @@ -88,7 +83,6 @@ The extension currently provides the following configuration options: .. _extconf-attributes-temperature: .. confval:: attributes.temperature - :type: float :Default: `0.5` @@ -98,7 +92,6 @@ The extension currently provides the following configuration options: .. _extconf-attributes-numberOfCompletions: .. confval:: attributes.numberOfCompletions - :type: integer :Default: `1` @@ -108,7 +101,6 @@ The extension currently provides the following configuration options: .. _extconf-cache-lifetime: .. confval:: cache.lifetime - :type: integer :Default: `86400` *(= 1 day)* diff --git a/Documentation/Contributing/Index.rst b/Documentation/Contributing/Index.rst index efa512b6..8b6a3607 100644 --- a/Documentation/Contributing/Index.rst +++ b/Documentation/Contributing/Index.rst @@ -1,5 +1,17 @@ .. include:: /Includes.rst.txt +.. image:: https://img.shields.io/coverallsCoverage/github/eliashaeussler/typo3-solver?logo=coveralls + :target: https://coveralls.io/github/eliashaeussler/typo3-solver + +.. image:: https://img.shields.io/codeclimate/maintainability/eliashaeussler/typo3-solver?logo=codeclimate + :target: https://codeclimate.com/github/eliashaeussler/typo3-solver/maintainability + +.. image:: https://img.shields.io/github/actions/workflow/status/eliashaeussler/typo3-solver/cgl.yaml?label=cgl&logo=github + :target: https://github.com/eliashaeussler/typo3-solver/actions/workflows/cgl.yaml + +.. image:: https://img.shields.io/github/actions/workflow/status/eliashaeussler/typo3-solver/tests.yaml?label=tests&logo=github + :target: https://github.com/eliashaeussler/typo3-solver/actions/workflows/tests.yaml + .. _contributing: ============ @@ -70,9 +82,6 @@ You can access the DDEV site at https://typo3-ext-solver.ddev.site/. Check code quality ------------------ -.. image:: https://github.com/eliashaeussler/typo3-solver/actions/workflows/cgl.yaml/badge.svg - :target: https://github.com/eliashaeussler/typo3-solver/actions/workflows/cgl.yaml - .. _cgl-typo3: TYPO3 @@ -128,14 +137,6 @@ Frontend Run tests --------- -.. image:: https://github.com/eliashaeussler/typo3-solver/actions/workflows/tests.yaml/badge.svg - :target: https://github.com/eliashaeussler/typo3-solver/actions/workflows/tests.yaml - -.. rst-class:: d-inline-block mb-3 - -.. image:: https://img.shields.io/coverallsCoverage/github/eliashaeussler/typo3-solver?logo=coveralls - :target: https://coveralls.io/github/eliashaeussler/typo3-solver - .. code-block:: bash # All tests diff --git a/Documentation/DeveloperCorner/Caching.rst b/Documentation/DeveloperCorner/Caching.rst index aa2e9958..5da01d52 100644 --- a/Documentation/DeveloperCorner/Caching.rst +++ b/Documentation/DeveloperCorner/Caching.rst @@ -7,7 +7,7 @@ Caching ======= Generated solutions can be cached if the solution provider in -use is cacheable (see :php:meth:`EliasHaeussler\\Typo3Solver\\ProblemSolving\\Solution\\Provider\\SolutionProvider::isCacheable`). +use is cacheable (see :php:meth:`\EliasHaeussler\Typo3Solver\ProblemSolving\Solution\Provider\SolutionProvider::isCacheable`). For this, a filesystem-based solution cache is implemented. In addition, an exception cache is provided which stores exceptions when :ref:`solution streaming ` is active. @@ -68,7 +68,7 @@ when :ref:`solution streaming ` is active. Get cached solution for the given problem. If no solution exists in cache, :php:`null` is returned. - :param EliasHaeussler\\Typo3Solver\\ProblemSolving\\Problem\\Problem $problem: Problem to get a cached solution for + :param EliasHaeussler\Typo3Solver\ProblemSolving\Problem\Problem $problem: Problem to get a cached solution for :returntype: EliasHaeussler\\Typo3Solver\\ProblemSolving\\Solution\\Solution|null .. php:method:: set($problem, $solution) @@ -76,8 +76,8 @@ when :ref:`solution streaming ` is active. Add the given solution to the solutions cache and use the given problem to generate the cache identifier. - :param EliasHaeussler\\Typo3Solver\\ProblemSolving\\Problem\\Problem $problem: The problem of the solution to be cached - :param EliasHaeussler\\Typo3Solver\\ProblemSolving\\Solution\\Solution $solution: The solution to be cached + :param EliasHaeussler\Typo3Solver\ProblemSolving\Problem\Problem $problem: The problem of the solution to be cached + :param EliasHaeussler\Typo3Solver\ProblemSolving\Solution\Solution $solution: The solution to be cached .. php:method:: flush() diff --git a/Documentation/DeveloperCorner/Formatters.rst b/Documentation/DeveloperCorner/Formatters.rst index 20339b45..a777cc14 100644 --- a/Documentation/DeveloperCorner/Formatters.rst +++ b/Documentation/DeveloperCorner/Formatters.rst @@ -19,8 +19,8 @@ Formatters are used to make a generated solution visible to the user. Format given problem and solution to string. - :param EliasHaeussler\\Typo3Solver\\ProblemSolving\\Problem\\Problem $problem: The problem to be formatted - :param EliasHaeussler\\Typo3Solver\\ProblemSolving\\Solution\\Solution $solution: The solution to be formatted + :param EliasHaeussler\Typo3Solver\ProblemSolving\Problem\Problem $problem: The problem to be formatted + :param EliasHaeussler\Typo3Solver\ProblemSolving\Solution\Solution $solution: The solution to be formatted :returntype: string .. _default-formatters: diff --git a/Documentation/DeveloperCorner/Middlewares.rst b/Documentation/DeveloperCorner/Middlewares.rst index d3e6a98c..0bd6db35 100644 --- a/Documentation/DeveloperCorner/Middlewares.rst +++ b/Documentation/DeveloperCorner/Middlewares.rst @@ -56,14 +56,13 @@ authentication layer. - :aspect:`Required parameters`: .. confval:: exception - :Required: true :type: string Cache identifier of the exception for which a solution is to provide. This identifier is returned when calling - :php:meth:`EliasHaeussler\\Typo3Solver\\Cache\\ExceptionsCache::set` - or :php:meth:`EliasHaeussler\\Typo3Solver\\Cache\\ExceptionsCache::getIdentifier`. + :php:meth:`\EliasHaeussler\Typo3Solver\Cache\ExceptionsCache::set` + or :php:meth:`\EliasHaeussler\Typo3Solver\Cache\ExceptionsCache::getIdentifier`. .. note:: @@ -73,7 +72,6 @@ authentication layer. .. _tx-solver-solution-hash: .. confval:: hash - :Required: true :type: string @@ -100,20 +98,18 @@ the :php:class:`EliasHaeussler\\Typo3Solver\\Formatter\\WebStreamFormatter`. It is passed as JSON string and contains the following properties: .. confval:: data - + :name: solutionDelta-data :type: object Contains solution metadata. .. confval:: model - :type: string The used OpenAI model. This normally matches the configured :ref:`model `. .. confval:: numberOfChoices - :type: int The number of choices provided by the current solution. This @@ -121,20 +117,19 @@ It is passed as JSON string and contains the following properties: :ref:`number of completions `. .. confval:: numberOfPendingChoices - :type: int The number of choices whose generation is not finished yet. As soon as this value is :php:`0`, the solution stream is finished. .. confval:: prompt - + :name: solutionDelta-prompt :type: string The prompt used to generate the solution. .. confval:: content - + :name: solutionDelta-content :type: string The current solution delta as formatted string. @@ -155,25 +150,23 @@ generation. Event data is passed as JSON string and contains the following properties: .. confval:: data - + :name: solutionError-data :type: object Contains exception metadata. .. confval:: message - :type: string The exception message. .. confval:: code - :type: int The exception code. .. confval:: content - + :name: solutionError-content :type: string The formatted exception, ready to replace the solution container @@ -201,10 +194,10 @@ is given as query parameter and validates it against a list of previously registered hashes. If the parameter is omitted, authentication fails. A stream hash can be registered by calling -:php:meth:`EliasHaeussler\\Typo3Solver\\Formatter\\Authentication\\StreamAuthentication::register`. +:php:`\EliasHaeussler\Typo3Solver\Formatter\Authentication\StreamAuthentication::register`. It generates a unique hash and writes it to a transient file. This file is then looked up on request by calling -:php:meth:`EliasHaeussler\\Typo3Solver\\Formatter\\Authentication\\StreamAuthentication::authenticate`. +:php:`\EliasHaeussler\Typo3Solver\Formatter\Authentication\StreamAuthentication::authenticate`. If the hash is registered, it is removed from the transient file and authentication is passed successfully. diff --git a/Documentation/DeveloperCorner/SolutionProviders.rst b/Documentation/DeveloperCorner/SolutionProviders.rst index a6101470..06afc02c 100644 --- a/Documentation/DeveloperCorner/SolutionProviders.rst +++ b/Documentation/DeveloperCorner/SolutionProviders.rst @@ -31,7 +31,7 @@ way to solve a given problem. Provide a solution for the given problem. - :param EliasHaeussler\\Typo3Solver\\ProblemSolving\\Problem\\Problem $problem: The problem to be solved + :param EliasHaeussler\Typo3Solver\ProblemSolving\Problem\Problem $problem: The problem to be solved :returntype: EliasHaeussler\\Typo3Solver\\ProblemSolving\\Solution\\Solution :throws: EliasHaeussler\\Typo3Solver\\Exception\\UnableToSolveException @@ -67,11 +67,11 @@ way to solve a given problem. .. php:method:: getStreamedSolution($problem) Provide a solution stream for the given problem. The stream is - returned as an instance of :php:interface:`Traversable`, while + returned as an instance of :php:`\Traversable`, while each traversed item is an instance of - :php:class:`EliasHaeussler\\Typo3Solver\\ProblemSolving\\Solution\\Solution`. + :php:`\EliasHaeussler\Typo3Solver\ProblemSolving\Solution\Solution`. - :param EliasHaeussler\\Typo3Solver\\ProblemSolving\\Problem\\Problem $problem: The problem to be solved + :param EliasHaeussler\Typo3Solver\ProblemSolving\Problem\Problem $problem: The problem to be solved :returntype: :php:`Traversable` :throws: EliasHaeussler\\Typo3Solver\\Exception\\UnableToSolveException @@ -102,7 +102,7 @@ the OpenAI endpoint. This provider decorates a concrete solution provider with an additional cache layer. The concrete solution provider must be provided in the - :php:meth:`EliasHaeussler\\Typo3Solver\\ProblemSolving\\Solution\\Provider\\SolutionProvider::create` + :php:meth:`\EliasHaeussler\Typo3Solver\ProblemSolving\Solution\Provider\SolutionProvider::create` method. .. note:: diff --git a/Documentation/Includes.rst.txt b/Documentation/Includes.rst.txt index 9ea9699c..23625074 100644 --- a/Documentation/Includes.rst.txt +++ b/Documentation/Includes.rst.txt @@ -1,17 +1 @@ -.. This is 'Includes.rst.txt'. It is included at the very top of each and - every ReST source file in THIS documentation project (= manual). - -.. role:: aspect (emphasis) -.. role:: html(code) -.. role:: js(code) -.. role:: php(code) -.. role:: sep (strong) -.. role:: sql(code) -.. role:: typoscript(code) -.. role:: yaml(code) - -.. role:: ts(typoscript) - :class: typoscript - -.. default-role:: code -.. highlight:: php +.. You can put central messages to display on all pages here diff --git a/Documentation/Index.rst b/Documentation/Index.rst index 48d248f7..84112c28 100644 --- a/Documentation/Index.rst +++ b/Documentation/Index.rst @@ -61,4 +61,3 @@ problems from command line. :hidden: Sitemap - genindex diff --git a/Documentation/Settings.cfg b/Documentation/Settings.cfg deleted file mode 100644 index 40ded093..00000000 --- a/Documentation/Settings.cfg +++ /dev/null @@ -1,17 +0,0 @@ -[general] -project = Solver -release = 0.2.14 -copyright = since 2023 by Elias Häußler -author = Elias Häußler - -[html_theme_options] -project_home = https://extensions.typo3.org/extension/solver -project_contact = https://typo3.slack.com/archives/C04Q3440HS6 -project_issues = https://github.com/eliashaeussler/typo3-solver/issues -github_branch = main -github_repository = eliashaeussler/typo3-solver -project_repository = https://github.com/eliashaeussler/typo3-solver - -[intersphinx_mapping] -t3coreapi = https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ -t3tsref = https://docs.typo3.org/m/typo3/reference-typoscript/main/en-us/ diff --git a/Documentation/Usage/ConsoleCommands.rst b/Documentation/Usage/ConsoleCommands.rst index 97d5ea97..7c779205 100644 --- a/Documentation/Usage/ConsoleCommands.rst +++ b/Documentation/Usage/ConsoleCommands.rst @@ -56,7 +56,6 @@ The following input parameters are available: .. _solver-solve-problem: .. confval:: problem - :Required: false :type: string :Default: none @@ -87,7 +86,6 @@ The following input parameters are available: .. _solver-solve-identifier: .. confval:: -i|--identifier - :Required: false :type: string :Default: none @@ -118,7 +116,6 @@ The following input parameters are available: .. _solver-solve-code: .. confval:: -c|--code - :Required: false :type: integer :Default: none @@ -149,7 +146,6 @@ The following input parameters are available: .. _solver-solve-file: .. confval:: -f|--file - :Required: false :type: string :Default: none @@ -180,7 +176,6 @@ The following input parameters are available: .. _solver-solve-line: .. confval:: -l|--line - :Required: false :type: integer :Default: none @@ -211,7 +206,6 @@ The following input parameters are available: .. _solver-solve-refresh: .. confval:: -r|--refresh - :Required: false :type: boolean :Default: false @@ -237,7 +231,6 @@ The following input parameters are available: .. _solver-solve-json: .. confval:: -j|--json - :Required: false :type: boolean :Default: false @@ -302,7 +295,6 @@ The following input parameters are available: .. _solver-list-models-all: .. confval:: -a|--all - :Required: false :type: boolean :Default: false @@ -355,7 +347,6 @@ cache entries, the command `solver:cache:flush` can be used. The following input parameters are available: .. confval:: identifier - :Required: false :type: string :Default: none diff --git a/Documentation/Usage/ExceptionHandler.rst b/Documentation/Usage/ExceptionHandler.rst index 93b2da5e..22fd2ccb 100644 --- a/Documentation/Usage/ExceptionHandler.rst +++ b/Documentation/Usage/ExceptionHandler.rst @@ -8,7 +8,7 @@ Exception handler The core component of this extension is to modify the default :ref:`debug exception handler ` -from TYPO3 core. For this, the :php:class:`EliasHaeussler\\Typo3Solver\\Error\\AiSolverExceptionHandler` +from TYPO3 core. For this, the :php:`\EliasHaeussler\Typo3Solver\Error\AiSolverExceptionHandler` class is shipped with the extension. .. _exception-handler-configuration: diff --git a/Documentation/genindex.rst b/Documentation/genindex.rst deleted file mode 100644 index 38a804f9..00000000 --- a/Documentation/genindex.rst +++ /dev/null @@ -1,7 +0,0 @@ -.. include:: /Includes.rst.txt - -===== -Index -===== - -.. Sphinx will insert here the general index automatically. diff --git a/Documentation/guides.xml b/Documentation/guides.xml new file mode 100644 index 00000000..3df12316 --- /dev/null +++ b/Documentation/guides.xml @@ -0,0 +1,19 @@ + + + + + + + diff --git a/composer.json b/composer.json index 054b3158..bfc5489b 100644 --- a/composer.json +++ b/composer.json @@ -77,9 +77,9 @@ "@docs:build", "@docs:open" ], - "docs:build": "docker-compose run --rm docs", + "docs:build": "docker compose run --rm docs", "docs:cleanup": "rm -rf .build/docs", - "docs:open": "open .build/docs/Result/project/0.0.0/Index.html", + "docs:open": "open .build/docs/Index.html", "test": [ "@test:functional", "@test:unit" diff --git a/docker-compose.yml b/docker-compose.yml index 0e165723..6b4d5a2a 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -1,9 +1,8 @@ -version: '3.6' - services: docs: - image: ghcr.io/t3docs/render-documentation:develop - command: makehtml + image: ghcr.io/typo3-documentation/render-guides + entrypoint: ['/opt/guides/entrypoint.sh', '--config', 'Documentation', '--output', '/result'] + pull_policy: always volumes: - - .:/PROJECT:ro - - .build/docs:/RESULT + - .:/project:ro + - .build/docs:/result diff --git a/version-bumper.yaml b/version-bumper.yaml index 322766fc..d4b3a504 100644 --- a/version-bumper.yaml +++ b/version-bumper.yaml @@ -1,7 +1,7 @@ filesToModify: - - path: Documentation/Settings.cfg + - path: Documentation/guides.xml patterns: - - 'release = {%version%}' + - 'release="{%version%}"' reportUnmatched: true - path: Resources/Private/Frontend/package.json patterns: