[FEATURE] Backend documentation module
[Packages/TYPO3.CMS.git] / typo3 / sysext / documentation / README.rst
1 .. ==================================================
2 .. FOR YOUR INFORMATION
3 .. --------------------------------------------------
4 .. -*- coding: utf-8 -*- with BOM.
5
6
7 .. _start:
8
9 =============
10 Documentation
11 =============
12
13 This extension provides a Backend module for TYPO3 to show both the documentation of local extensions and custom
14 documents.
15
16 The Backend module features two actions:
17
18 #. Show Documentation
19 #. Manage Documentation
20
21
22 Show Documentation
23 ==================
24
25 This view shows a list of available documents:
26
27 - Extensions with a manual rendered as ``html`` or ``pdf``;
28 - Extensions with an OpenOffice manual (``sxw``);
29 - Official TYPO3 documentation (tutorials, references, ...) available locally;
30 - Custom documents, rendered either as ``html`` or ``pdf``.
31
32 To be listed, documents should be stored within ``typo3conf/Documentation/<documentation-key>/<language>/<format>/``:
33
34 ``documentation-key``
35 Extensions use the documentation key ``typo3cms.extensions.<extension-key>``.
36
37 ``language``
38 Either "default" (for English) or some (generally) two-letter ISO code identifying a translation of your document.
39
40 ``format``
41 Either ``html`` or ``pdf``. Additional formats may be supported by 3rd party extensions (such as EXT:sphinx).
42
43
44 Registering Custom Documents
45 ----------------------------
46
47 #. Choose a documentation key such as ``<company>.<document-name>``
48
49 #. Put your documentation as HTML (main file *must be* ``Index.html``) within
50 ``typo3conf/Documentation/<documentation-key>/default/html/`` or as PDF (any name will fit) within
51 ``typo3conf/Documentation/<documentation-key>/default/pdf/``
52
53 #. Create a text description file ``composer.json`` containing the title and description of your documentation and place
54 it within ``typo3conf/Documentation/<documentation-key>/default/``:
55
56 .. code-block:: json
57
58 {
59 "name": "Put some title here",
60 "type": "documentation",
61 "description": "Put some description here."
62 }
63
64 #. [optionally] Put a custom icon (either ``icon.png`` or ``icon.gif``) within directory
65 ``typo3conf/Documentation/<documentation-key>/``
66
67
68 Manage Documentation
69 ====================
70
71 This view is only accessible to TYPO3 administrators. It shows a form to retrieve rendered documentation for loaded
72 extensions and to fetch a copy of official TYPO3 manuals, guides and references from http://docs.typo3.org.
73
74
75 Configuration
76 =============
77
78 There are two User TSconfig options available:
79
80 mod.help_DocumentationDocumentation.documents.hide
81 Comma-separated list of keys of documentation that should be hidden from the user.
82
83 mod.help_DocumentationDocumentation.documents.show
84 Comma-separated list of keys of documentation that should be shown to the user (others are implicitly hidden).
85