What does it do?

This extension lets you build documentation projects written with Sphinx (the Python Documentation Generator used by the TYPO3 documentation team for all official documentation) from within the TYPO3 Backend:

|

The name of this extension comes from the underlying markup language used by Sphinx. In fact, Sphinx uses reStructuredText (commonly abbreviated as reST) as its markup language.

Sphinx was originally created for the Python documentation and a few features are worth highlighting:

• Output formats: HTML, JSON (a derivate from HTML this extension is relying on), LaTeX (for printable PDF versions), plain text, ...
• Extensive cross-references: semantic markup and automatic links for citations, glossary terms and similar pieces of information. For instance, the official TYPO3 documentation provides resources to cross-link from your own documentation to virtually any chapter or section of any TYPO3 documentation. Please consult page Tips and Tricks in the TYPO3 wiki for more information.
• Hierarchical structure: easy definition of a document tree, with automatic links to siblings, parents and children
• Automatic index: general index of terms used in your documentation
• Extensions: the tool lets you extend it with your own modules

Screenshots

|plugin_options|

Search Form

A search form may be generated with option (SEARCH).

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.

Configure Routing

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

routeEnhancers:
  Restdoc:
    type: RestdocPlugin
    limitToPages: [1]

You should naturally adapt limitToPages to the pages where the restdoc plugin is located. If you don't, the plugin will determine that dynamically but this will have a small performance penalty. You may figure out the list by running this SQL query:

SELECT
    DISTINCT pid
FROM
    tt_content
WHERE
    CType = 'list'
    AND list_type = 'restdoc_pi1'
    AND sys_language_uid = 0 AND deleted = 0;

This will default to extend your configuration like that:

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

Naturally you may override the routePath and corresponding requirements to fit your own special use case, if needed.

Available modes for the plugin

When integrating the plugin with TypoScript, additional modes of operations are available. These are:

TOC

Generates a table of contents

MASTER_TOC

Generates the master table of contents

RECENT

Renders a list of chapters updated recently

BODY

Generates the documentation itself

TITLE

Returns the current chapter's title

QUICK_NAVIGATION

Generates a quick navigation with "previous", "next", "home", ...

BREADCRUMB

Generates a breadcrumb menu for the current chapter

REFERENCES

Generates a list of references within the whole documentation

FILENAME

Returns the name of the .fjson being rendered

SEARCH

Generates a search form

Additional Content Object

This extension registers an additional content object to let you access meta-information from your documentation. Example:

10 = REST_METADATA
10 {
    path = {$plugin.tx_restdoc.path}
    field = copyright
    noTrimWrap = |Copyright © ||
}

Please read next chapter for a list of available fields.

Properties

Property details

<div class="tx-restdoc-pi1">
    ...
</div>

Properties

Property details

Properties

Property details

10 = REST_METADATA
10.field = copyright

Hooks

Extending even more

In case you want to really extend the output, you may want to take a whole different approach and only take advantage of the internal Sphinx JSON reader but create the plugin on your own, possibly using Extbase instead of the plugin we provide.

In that case, be sure to have a look at this project to inspire from: https://github.com/xperseguers/t3ext-docstypo3org

Registration

You should register your class in:

$GLOBALS['TYPO3_CONF_VARS']['EXTCONF']['restdoc']['renderHook']

Expected method

Your hook should implement a method postProcessOutput() of the form

public function postProcessOutput(array $params)
{
    // Custom code
}

Parameters

$params is an array with following keys:

mode

The plugin's mode

documentRoot

Absolute path to the documentation's root

document

Relative path to the current document

output

Reference to the output of the plugin, may thus be changed within your hook

config

Configuration of the plugin

pObj

A reference to the current \Causal\Restdoc\Controller\Pi1\Pi1Controller instance

Registration

You should register your class in:

$GLOBALS['TYPO3_CONF_VARS']['EXTCONF']['restdoc']['makeMenuArrayHook']

Expected method

Your hook should implement a method postProcessTOC() of the form

public function postProcessTOC(array $params)
{
    // Custom code
}

Parameters

$params is an array with following keys:

documentRoot

Absolute path to the documentation's root

document

Relative path to the current document

data

A reference to an array of menu entries compatible with the various *MENU content objects, may thus be changed within your hook

config

Configuration of the plugin

pObj

A reference to the current \Causal\Restdoc\Controller\Pi1\Pi1Controller instance

Registration

You should register your class in:

$GLOBALS['TYPO3_CONF_VARS']['EXTCONF']['restdoc']['quickNavigationHook']

Expected method

Your hook should implement a method postProcessQUICK_NAVIGATION() of the form

public function postProcessQUICK_NAVIGATION(array $params)
{
    // Custom code
}

Parameters

$params is an array with following keys:

documentRoot

Absolute path to the documentation's root

document

Relative path to the current document

data

A reference to an array with the various links, may thus be changed within your hook. Available keys:

• home_title / home_uri / home_uri_absolute
• previous_title / previous_uri / previous_uri_absolute
• next_title / next_uri / next_uri_absolute
• parent_title / parent_uri / parent_uri_absolute
• index_title / index_uri / index_uri_absolute
• has_previous / has_next / has_parent / has_index

config

Configuration of the plugin

pObj

A reference to the current \Causal\Restdoc\Controller\Pi1\Pi1Controller instance

Registration

You should register your class in:

$GLOBALS['TYPO3_CONF_VARS']['EXTCONF']['restdoc']['searchFormHook']

Expected method

Your hook should implement a method preProcessSEARCH() of the form

public function preProcessSEARCH(array $params)
{
    // Custom code
}

Parameters

$params is an array with following keys:

config

A reference to the configuration of the search form:

• jsLibs: Array of JavaScript libraries to be loaded (underscore.js, doctools.js, searchtools.js)
• jsInline: Inline JavaScript code (loading the index resource)
• advertiseSphinx: Whether to advertise Sphinx (standard inline JavaScript code needed by searchtools.js, thus default to TRUE)

pObj

A reference to the current \Causal\Restdoc\Controller\Pi1\Pi1Controller instance

Translation

Another very easy way to contribute to the success of this extension is to translate it on the Crowdin translation server; other users will thank you much.

How to contribute

This extension is using the same contribution workflow as for TYPO3 Core, but with GitHub PRs for the review process. Please read more about the workflow in the TYPO3 Contribution Guide.