Installing the extension

There are a few steps necessary to install the Sphinx Documentation Viewer Plugin extension. If you have installed other extensions in the past, you will run into little new here.

Install the extension from Extension Manager

The Sphinx Documentation Viewer Plugin extension can ben installed through the typical TYPO3 installation process using the Extension Manager.

The Extension Manager will create a new table in your database. This table is used to store references to the chapters in the context of the plugin and is used to both generate the menu of recent updates in your documentation and to integrate the structure of your documentation within your website’s sitemap, when using this extension together with dd_googlesitemap.

Configure Routing (since TYPO3 v9)

In order to get pretty URL, you are advised to edit file config/sites/*/config.yaml and extend it like that:

routeEnhancers:
  Restdoc:
    type: Plugin
    limitToPages: [1]
    routePath: '/{doc}'
    namespace: 'tx_restdoc_pi1'
    requirements:
      doc: '.+'

You should naturally adapt limitToPages to the pages where the restdoc plugin is located.

Configure RealURL (TYPO3 v8)

If you are using RealURL, the good news is that the Sphinx Documentation Viewer Plugin extension comes with a configuration for RealURL.

If your configuration is automatically generated (you have a typo3conf/realurl_autoconf.php file), delete it. It will be recreated by RealURL the next time you render your page and will integrate our postVarSets configuration.

If you manually tweaked the configuration (you have a typo3conf/realurl_conf.php file), here is the configuration we suggest:

'postVarSets' => [
    '_DEFAULT' => [
        'chapter' => [
            [
                'GETvar' => 'tx_restdoc_pi1[doc]',
            ],
        ],
    ],
],

You may even fully and transparently embed your documentation within the URL, without any “chapter” segment if you use a forward slash for plugin.tx_restdoc_pi1.pathSeparator and enable this behaviour in Extension Manager.

'fixedPostVars' => [
    '123' => 'restdoc_advanced_url',
    '456' => 'restdoc_advanced_url',
    'restdoc_advanced_url' => [
        [
            'GETvar' => 'tx_restdoc_pi1[doc]',
            'userFunc' => \Causal\Restdoc\Hooks\Realurl::class . '->decodeSpURL_getSequence',
        ],
    ],
],

where 123 and 456 are page uids with a restdoc plugin.

Hint

If you switch from standard configuration with a pipe (|) as separator to a forward slash, you probably should consider adding the pipe to the comma-separated list of plugin.tx_restdoc_pi1.fallbackPathSeparator to prevent invalidating every existing search engine page result.

Note

If you generate links to chapters in TypoScript, you may need to manually replace the encoded forward slash (%2F) to a non-encoded one (/) with stdWrap’s replacement.