Merge pull request #269 from eliashaeussler/task/docs

.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

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 <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)*
 

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

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 <streamed-solution>` is active.
@@ -68,16 +68,16 @@ when :ref:`solution streaming <streamed-solution>` 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)
 
         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()
 

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:

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,41 +98,38 @@ 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 <extconf-attributes-model>`.
 
     ..  confval:: numberOfChoices
-
         :type: int
 
         The number of choices provided by the current solution. This
         normally matches the configured
         :ref:`number of completions <extconf-attributes-numberOfCompletions>`.
 
     ..  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.
 

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<EliasHaeussler\Typo3Solver\ProblemSolving\Solution\Solution>`
         :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::

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

Documentation/Index.rst

@@ -61,4 +61,3 @@ problems from command line.
     :hidden:
 
     Sitemap
-    genindex