Merge pull request #80 from eliashaeussler/task/docs

eliashaeussler · Oct 15, 2024 · 7d2a1ea · 7d2a1ea
2 parents 21efa61 + d2f87d7
commit 7d2a1ea
Show file tree

Hide file tree

Showing 16 changed files with 72 additions and 116 deletions.
diff --git a/.github/workflows/cgl.yaml b/.github/workflows/cgl.yaml
@@ -59,3 +59,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/SiteConfiguration.rst b/Documentation/Configuration/SiteConfiguration.rst
@@ -11,7 +11,6 @@ the path to a related XML sitemap. The following configuration options are avail
 for this purpose:
 
 ..  confval:: xml_sitemap_path (site)
-
     :Path: xml_sitemap_path
     :type: string
 
@@ -22,7 +21,6 @@ for this purpose:
         :alt: Configuration of XML sitemap path within the Sites module
 
 ..  confval:: xml_sitemap_path (site_language)
-
     :Path: languages > (site language) > xml_sitemap_path
     :type: string
 

diff --git 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-sitemap-locator?logo=coveralls
+    :target: https://coveralls.io/github/eliashaeussler/typo3-sitemap-locator
+
+..  image:: https://img.shields.io/codeclimate/maintainability/eliashaeussler/typo3-sitemap-locator?logo=codeclimate
+    :target: https://codeclimate.com/github/eliashaeussler/typo3-sitemap-locator/maintainability
+
+..  image:: https://img.shields.io/github/actions/workflow/status/eliashaeussler/typo3-sitemap-locator/cgl.yaml?label=cgl&logo=github
+    :target: /~https://github.com/eliashaeussler/typo3-sitemap-locator/actions/workflows/cgl.yaml
+
+..  image:: https://img.shields.io/github/actions/workflow/status/eliashaeussler/typo3-sitemap-locator/tests.yaml?label=tests&logo=github
+    :target: /~https://github.com/eliashaeussler/typo3-sitemap-locator/actions/workflows/tests.yaml
+
 ..  _contributing:
 
 ============
@@ -69,11 +81,6 @@ You can access the DDEV site at https://typo3-ext-sitemap-locator.ddev.site/.
 Check code quality
 ------------------
 
-..  rst-class:: d-inline-block mb-3
-
-..  image:: /~https://github.com/eliashaeussler/typo3-sitemap-locator/actions/workflows/cgl.yaml/badge.svg
-    :target: /~https://github.com/eliashaeussler/typo3-sitemap-locator/actions/workflows/cgl.yaml
-
 ..  code-block:: bash
 
     # All linters
@@ -103,14 +110,6 @@ Check code quality
 Run tests
 ---------
 
-..  image:: /~https://github.com/eliashaeussler/typo3-sitemap-locator/actions/workflows/tests.yaml/badge.svg
-    :target: /~https://github.com/eliashaeussler/typo3-sitemap-locator/actions/workflows/tests.yaml
-
-..  rst-class:: d-inline-block mb-3
-
-..  image:: https://img.shields.io/coverallsCoverage/github/eliashaeussler/typo3-sitemap-locator?logo=coveralls
-    :target: https://coveralls.io/github/eliashaeussler/typo3-sitemap-locator
-
 ..  code-block:: bash
 
     # All tests

diff --git a/Documentation/DeveloperCorner/Caching.rst b/Documentation/DeveloperCorner/Caching.rst
@@ -21,8 +21,8 @@ the path to the XML sitemap is cached. Caching happens with a custom
 
         Get the located sitemaps of a given site.
 
-        :param TYPO3\\CMS\\Core\\Site\\Entity\\Site $site: The sitemap's site object.
-        :param TYPO3\\CMS\\Core\\Site\\Entity\\SiteLanguage $siteLanguage: An optional site language.
+        :param TYPO3\CMS\Core\Site\Entity\Site $site: The sitemap's site object.
+        :param TYPO3\CMS\Core\Site\Entity\SiteLanguage $siteLanguage: An optional site language.
         :returns: Located sitemaps of a given site.
 
     ..  php:method:: set($sitemaps)

diff --git a/Documentation/DeveloperCorner/Events.rst b/Documentation/DeveloperCorner/Events.rst
@@ -18,7 +18,7 @@ SitemapsLocatedEvent
 ====================
 
 This event is dispatched right after an XML sitemap is located via
-:php:meth:`EliasHaeussler\\Typo3SitemapLocator\\Sitemap\\SitemapLocator::locateBySite`.
+:php:`\EliasHaeussler\Typo3SitemapLocator\Sitemap\SitemapLocator::locateBySite`.
 It allows to modify the list of located XML sitemaps and also provides
 the used site and site language.
 
@@ -27,7 +27,7 @@ the used site and site language.
 SitemapValidatedEvent
 =====================
 
-When :php:meth:`EliasHaeussler\\Typo3SitemapLocator\\Sitemap\\SitemapLocator::isValidSitemap`
+When :php:`\EliasHaeussler\Typo3SitemapLocator\Sitemap\SitemapLocator::isValidSitemap`
 is called, a request to the given sitemap URL is dispatched. If this
 request fails or returns a status code of `400` or higher, the sitemap
 is considered invalid. Right after the validity check, this event is

diff --git a/Documentation/DeveloperCorner/SitemapProviders.rst b/Documentation/DeveloperCorner/SitemapProviders.rst
@@ -21,9 +21,9 @@ priority) to localize XML sitemaps according to certain criteria.
 
         Locate XML sitemaps of the given site.
 
-        :param TYPO3\\CMS\\Core\\Site\\Entity\\Site $site: The site whose XML sitemap path should be located.
-        :param TYPO3\\CMS\\Core\\Site\\Entity\\SiteLanguage $siteLanguage: An optional site language to include while locating the XML sitemap path.
-        :returns: An array of instances of :php:class:`EliasHaeussler\\Typo3SitemapLocator\\Domain\\Model\\Sitemap`.
+        :param TYPO3\CMS\Core\Site\Entity\Site $site: The site whose XML sitemap path should be located.
+        :param TYPO3\CMS\Core\Site\Entity\SiteLanguage $siteLanguage: An optional site language to include while locating the XML sitemap path.
+        :returns: An array of instances of :php:`\EliasHaeussler\Typo3SitemapLocator\Domain\Model\Sitemap`.
 
     ..  php:staticmethod:: getPriority()
 
@@ -77,23 +77,23 @@ Implement a custom provider
 ===========================
 
 To develop your own sitemap provider, it is only necessary to
-implement the :php:interface:`EliasHaeussler\\Typo3SitemapLocator\\Sitemap\\Provider\\Provider`
+implement the :php:`\EliasHaeussler\Typo3SitemapLocator\Sitemap\Provider\Provider`
 interface. In addition, the :php:`getPriority()` method must be
 used to define when the provider is executed.
 
 The order of the providers provided by default is as follows:
 
-+----------------------------------------------------------------------------------------+---------------------+
-| Sitemap provider                                                                       | Priority            |
-+========================================================================================+=====================+
-| :php:class:`EliasHaeussler\\Typo3SitemapLocator\\Sitemap\\Provider\\PageTypeProvider`  | 300                 |
-+----------------------------------------------------------------------------------------+---------------------+
-| :php:class:`EliasHaeussler\\Typo3SitemapLocator\\Sitemap\\Provider\\SiteProvider`      | 200                 |
-+----------------------------------------------------------------------------------------+---------------------+
-| :php:class:`EliasHaeussler\\Typo3SitemapLocator\\Sitemap\\Provider\\RobotsTxtProvider` | 100                 |
-+----------------------------------------------------------------------------------------+---------------------+
-| :php:class:`EliasHaeussler\\Typo3SitemapLocator\\Sitemap\\Provider\\DefaultProvider`   | :php:`PHP_INT_MIN`  |
-+----------------------------------------------------------------------------------------+---------------------+
++-------------------------------------------------------------------------------+---------------------+
+| Sitemap provider                                                              | Priority            |
++===============================================================================+=====================+
+| :php:`\EliasHaeussler\Typo3SitemapLocator\Sitemap\Provider\PageTypeProvider`  | 300                 |
++-------------------------------------------------------------------------------+---------------------+
+| :php:`\EliasHaeussler\Typo3SitemapLocator\Sitemap\Provider\SiteProvider`      | 200                 |
++-------------------------------------------------------------------------------+---------------------+
+| :php:`\EliasHaeussler\Typo3SitemapLocator\Sitemap\Provider\RobotsTxtProvider` | 100                 |
++-------------------------------------------------------------------------------+---------------------+
+| :php:`\EliasHaeussler\Typo3SitemapLocator\Sitemap\Provider\DefaultProvider`   | :php:`PHP_INT_MIN`  |
++-------------------------------------------------------------------------------+---------------------+
 
 Once your custom provider is ready, make sure to clear the DI
 caches in order to rebuild the service container properly.

diff --git a/Documentation/Includes.rst.txt b/Documentation/Includes.rst.txt
@@ -1,35 +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:: css(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 PHP syntax highlighting
-
-..  highlight:: php
+..  You can put central messages to display on all pages here
diff --git a/Documentation/Index.rst b/Documentation/Index.rst
@@ -122,4 +122,3 @@ sitemap providers.
     :hidden:
 
     Sitemap
-    genindex
diff --git a/Documentation/Settings.cfg b/Documentation/Settings.cfg
diff --git a/Documentation/Usage/ConsoleCommands.rst b/Documentation/Usage/ConsoleCommands.rst
@@ -33,7 +33,6 @@ language.
 The following command options are available:
 
 ..  confval:: site
-
     :Required: true
     :type: integer (root page ID) or string (site identifier)
     :Default: none
@@ -61,7 +60,6 @@ The following command options are available:
                 typo3/sysext/core/bin/typo3 sitemap-locator:locate main
 
 ..  confval:: -l|--language
-
     :Required: false
     :type: integer
     :Default: none (= default language)
@@ -89,7 +87,6 @@ The following command options are available:
                 typo3/sysext/core/bin/typo3 sitemap-locator:locate --language 1
 
 ..  confval:: -a|--all
-
     :Required: false
     :type: boolean
     :Default: false
@@ -116,7 +113,6 @@ The following command options are available:
                 typo3/sysext/core/bin/typo3 sitemap-locator:locate --all
 
 ..  confval:: --validate
-
     :Required: false
     :type: boolean
     :Default: false
@@ -144,7 +140,6 @@ The following command options are available:
                 typo3/sysext/core/bin/typo3 sitemap-locator:locate --validate
 
 ..  confval:: -j|--json
-
     :Required: false
     :type: boolean
     :Default: false

diff --git a/Documentation/Usage/UsingTheAPI.rst b/Documentation/Usage/UsingTheAPI.rst
@@ -20,30 +20,30 @@ Read more about how to use this API on this page.
 
         Locate XML sitemaps of the given site and site language.
 
-        :param TYPO3\\CMS\\Core\\Site\\Entity\\Site $site: The site whose XML sitemap path should be located.
-        :param TYPO3\\CMS\\Core\\Site\\Entity\\SiteLanguage $siteLanguage: An optional site language to include while locating the XML sitemap path.
-        :returns: An array of instances of :php:class:`EliasHaeussler\\Typo3SitemapLocator\\Domain\\Model\\Sitemap`.
+        :param TYPO3\CMS\Core\Site\Entity\Site $site: The site whose XML sitemap path should be located.
+        :param TYPO3\CMS\Core\Site\Entity\SiteLanguage $siteLanguage: An optional site language to include while locating the XML sitemap path.
+        :returns: An array of instances of :php:`\EliasHaeussler\Typo3SitemapLocator\Domain\Model\Sitemap`.
 
     ..  php:method:: locateAllBySite($site)
 
         Locate XML sitemaps of the given site and all their available languages.
 
-        :param TYPO3\\CMS\\Core\\Site\\Entity\\Site $site: The site whose XML sitemap path should be located.
-        :returns: An array of instances of :php:class:`EliasHaeussler\\Typo3SitemapLocator\\Domain\\Model\\Sitemap`, indexed by the site language id.
+        :param TYPO3\CMS\Core\Site\Entity\Site $site: The site whose XML sitemap path should be located.
+        :returns: An array of instances of :php:`\EliasHaeussler\Typo3SitemapLocator\Domain\Model\Sitemap`, indexed by the site language id.
 
     ..  php:method:: isValidSitemap($sitemap)
 
         Check whether the given sitemap actually exists.
 
-        :param EliasHaeussler\\Typo3SitemapLocator\\Domain\\Model\\Sitemap $sitemap: The XML sitemap to check for existence
+        :param EliasHaeussler\Typo3SitemapLocator\Domain\Model\Sitemap $sitemap: The XML sitemap to check for existence
         :returntype: bool
 
 ..  _api-example:
 
 Example
 =======
 
-::
+..  code-block:: php
 
     use EliasHaeussler\Typo3SitemapLocator;
     use TYPO3\CMS\Core;

diff --git a/Documentation/genindex.rst b/Documentation/genindex.rst
diff --git a/Documentation/guides.xml b/Documentation/guides.xml
@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<guides xmlns="https://www.phpdoc.org/guides"
+        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+        xsi:schemaLocation="https://www.phpdoc.org/guides ../.Build/vendor/phpdocumentor/guides-cli/resources/schema/guides.xsd"
+        links-are-relative="true"
+>
+    <extension class="\T3Docs\Typo3DocsTheme\DependencyInjection\Typo3DocsThemeExtension"
+               project-home="https://extensions.typo3.org/extension/sitemap_locator"
+               project-contact="https://typo3.slack.com/archives/C060KATSL5V"
+               project-repository="/~https://github.com/eliashaeussler/typo3-sitemap-locator"
+               project-issues="/~https://github.com/eliashaeussler/typo3-sitemap-locator/issues"
+               edit-on-github-branch="main"
+               edit-on-github="eliashaeussler/typo3-sitemap-locator"
+               typo3-core-preferred="main"
+    />
+    <project title="Sitemap Locator" release="0.1.6" copyright="since 2023 by Elias Häußler"/>
+    <inventory id="t3coreapi" url="https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/"/>
+</guides>
diff --git a/composer.json b/composer.json
@@ -67,9 +67,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
@@ -1,9 +1,8 @@
-version: '3.6'
-
 services:
   docs:
-    image: ghcr.io/t3docs/render-documentation
-    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
@@ -1,8 +1,7 @@
 filesToModify:
-  - path: Documentation/Settings.cfg
+  - path: Documentation/guides.xml
     patterns:
-      - 'release = {%version%}'
-    reportUnmatched: true
+      - 'release="{%version%}"'
   - path: ext_emconf.php
     patterns:
       - "'version' => '{%version%}'"
Original file line number	Diff line number	Diff line change
Expand Up		@@ -122,4 +122,3 @@ sitemap providers.
		:hidden:

		Sitemap
		genindex