Commit 2bf48fff authored by Stefan Busemann's avatar Stefan Busemann
Browse files

[TASK] Add documentation template

parent e8995613
.. include:: ../Includes.txt
.. _changelog:
=========
ChangeLog
=========
Providing a change log chapter is optional. You can also refer
users to the ChangeLog file inside the extension or to some repository's
commit listing.
.. include:: ../Includes.txt
.. _configuration:
=============
Configuration
=============
Target group: **Developers, Integrators**
How to configure the extension. Try to make it easy to configure the extension.
Give a minimal example or a typical example.
Minimal Example
===============
- Is it necessary to include a static template file?
- For example add a code snippet with comments
Minimal example of TypoScript:
.. code-block:: none
plugin.tx_myextension.settings {
# configure basic email settings
email {
subject = Some subject
from = someemail@domain.de
}
}
.. _configuration-typoscript:
TypoScript Reference
====================
Possible subsections: Reference of TypoScript options.
The construct below show the recommended structure for
TypoScript properties listing and description.
When detailing data types or standard TypoScript
features, don't hesitate to cross-link to the TypoScript
Reference as shown below.
See `Hyperlinks & Cross-Referencing <https://docs.typo3.org/typo3cms/HowToDocument/WritingReST/Hyperlinks.html>`
for information about how to use cross-references.
See the :file:`Settings.cgf` file for the declaration of cross-linking keys.
You can add more keys besides tsref.
Properties
==========
.. container:: ts-properties
=========================== ===================================== ======================= ====================
Property Data type :ref:`t3tsref:stdwrap` Default
=========================== ===================================== ======================= ====================
allWrap_ :ref:`t3tsref:data-type-wrap` yes :code:`<div>|</div>`
`subst\_elementUid`_ :ref:`t3tsref:data-type-boolean` no 0
wrapItemAndSub_ :ref:`t3tsref:data-type-wrap`
=========================== ===================================== ======================= ====================
Property details
================
.. only:: html
.. contents::
:local:
:depth: 1
.. _ts-plugin-tx-extensionkey-allwrap:
allWrap
-------
:typoscript:`plugin.tx_extensionkey.allWrap =` :ref:`t3tsref:data-type-wrap`
Wraps the whole item.
.. _ts-plugin-tx-extensionkey-substelementUid:
subst_elementUid
----------------
:typoscript:`plugin.tx_extensionkey.subst_elementUid =` :ref:`t3tsref:data-type-boolean`
If set, all appearances of the string ``{elementUid}`` in the total
element html-code (after wrapped in allWrap_) are substituted with the
uid number of the menu item. This is useful if you want to insert an
identification code in the HTML in order to manipulate properties with
JavaScript.
.. _ts-plugin-tx-extensionkey-wrapitemandsub:
wrapItemAndSub
--------------
:typoscript:`plugin.tx_extensionkey.wrapItemAndSub =` :ref:`t3tsref:data-type-wrap`
Wraps the whole item and any submenu concatenated to it.
.. _configuration-faq:
FAQ
===
Possible subsection: FAQ
.. include:: ../Includes.txt
.. _contribute:
==========
Contribute
==========
Do you want people to contribute to your extension?
Here, you can add information about conventions you use when developing.
You may want to base this on already existing conventions for the TYPO3
core and for TYPO3 documentation.
If your project is hosted on GitHub, it is a good idea to add a file:`CONTRIBUTING.rst`
file. This sample template manual has one. A link to that file will automatically
be displayed by GitHub if people enter the issues section of your project for the first time
or create an issue.
The file:`CONTRIBUTING.rst` will not be displayed, when your extension is rendered on
docs.typo3.org though (because file:`CONTRIBUTING.rst` is outside of the scope of
the file:`Documentation` folder).
So, as not to create duplicate information, either use this file as main information
source about contributing and link to this page from file:`CONTRIBUTING.rst` or the other
way around.
**Sample text follows ...**
Contribution to this extension is very welcome.
If you wish to contribute, please follow these conventions:
Writing Issues
==============
* If you find a problem in the extension, please write an issue.
* If you can fix the problem yourself, please submit a pull request. In this
case, it is not necessary to create an issue first.
Submitting a Pull Request
=========================
* Please adhere to `TYPO3 Coding Guidelines
<https://docs.typo3.org/typo3cms/CoreApiReference/CodingGuidelines/Index.html>`__
* For commit messages, please follow the `TYPO3 Commit Message Rules
<https://docs.typo3.org/typo3cms/ContributionWorkflowGuide/Appendix/CommitMessage.html>`__
Please see the general GitHub documentation for more information, for example
`Creating a pull request <https://help.github.com/articles/creating-a-pull-request/>`__
Donate
======
Here, you can add a link to how people can support you and donate for your extension.
\ No newline at end of file
.. include:: ../Includes.txt
.. _developer:
================
Developer Corner
================
Target group: **Developers**
Use this section for *providing code examples* or any **useful** information code wise.
.. _developer-hooks:
Hooks
=====
Possible hook examples. Input parameters are:
+----------------+---------------+---------------------------------+
| Parameter | Data type | Description |
+================+===============+=================================+
| $table | string | Name of the table |
+----------------+---------------+---------------------------------+
| $field | string | Name of the field |
+----------------+---------------+---------------------------------+
Use parameter :code:`$table` to retrieve the table name...
.. _developer-api:
API
===
How to use the API...
.. code-block:: php
$stuff = \TYPO3\CMS\Core\Utility\GeneralUtility::makeInstance(
'\\Foo\\Bar\\Utility\\Stuff'
);
$stuff->do();
or some other language:
.. code-block:: javascript
:linenos:
:emphasize-lines: 2-4
$(document).ready(
function () {
doStuff();
}
);
.. ==================================================
.. FOR YOUR INFORMATION
.. --------------------------------------------------
.. -*- coding: utf-8 -*- with BOM.
.. This is 'Includes.txt'. It is included at the very top of each and
every ReST source file in this documentation project (= manual).
.. ==================================================
.. DEFINE SOME TEXT ROLES
.. --------------------------------------------------
.. role:: typoscript(code)
.. role:: ts(typoscript)
:class: typoscript
.. role:: php(code)
.. highlight:: php
.. include:: Includes.txt
.. Every manual should have a start label for cross-referencing to
.. start page. Do not remove this!
.. _start:
=============================================================
Extension Name
=============================================================
.. only:: html
:Classification:
<extension key>
:Version:
|release|
:Language:
en
:Description:
Manual covering TYPO3 extension <extension name>
:Keywords:
comma,separated,list,of,keywords
:Copyright:
2013-2019
:Author:
Your name
:Email:
you@domain.tld
:License:
This document is published under the Open Publication License
available from http://www.opencontent.org/openpub/
:Rendered:
|today|
The content of this document is related to TYPO3,
a GNU/GPL CMS/Framework available from `www.typo3.org <https://typo3.org/>`__.
**Table of Contents**
.. toctree::
:maxdepth: 3
Introduction/Index
User/Index
Installation/Index
Configuration/Index
Developer/Index
KnownProblems/Index
ToDoList/Index
ChangeLog/Index
Support/Index
Links
.. include:: ../Includes.txt
.. _installation:
============
Installation
============
Target group: **Administrators**
- How should the extension be installed?
- Are there dependencies to resolved?
Next step
=========
:ref:`Configure extension <configuration>`.
\ No newline at end of file
.. include:: ../Includes.txt
.. _introduction:
============
Introduction
============
.. _what-it-does:
What does it do?
================
This chapter should give a brief overview of the extension. What does it do? What problems does it solve?
Who is interested in this? Basically, this section includes everything people need to know to decide whether they
should go on with this extension or not.
.. important::
Please don't forget to repeat your extension's version number in the
:file:`Settings.cfg` file, in the :code:`release` property. It will be
automatically picked up on the cover page by the :code:`|release|`
substitution.
.. _screenshots:
Screenshots
===========
This chapter should help people figure how the extension works. Remove it
if not relevant.
.. figure:: ../Images/IntroductionPackage.png
:width: 500px
:alt: Introduction Package
Introduction Package just after installation (caption of the image)
How the Frontend of the Introduction Package looks like just after installation (legend of the image)
.. include:: ../Includes.txt
.. _known-problems:
==============
Known Problems
==============
Use this section for informing about any type of of problem
that are not necessarily named in the bug tracker such as performance issues, ...
.. include:: Includes.txt
.. _links:
Links
-----
The links to issue and the GitHub repository are maintained in the Settings.cfg.
You may want to remove this file if all important links are already handled in
Settings.cfg.
:Packagist:
https://packagist.org/packages/<username>/<extension key>
:TER:
https://typo3.org/extensions/repository/view/<extension key>
:Issues:
https://github.com/<username>/<extension key>/issues
:GitHub Repository:
https://github.com/<username>/<extension key>
:Contact:
`@<username> <https://twitter.com/your-username>`__
# coding: utf-8
# #####
#
# Settings.cfg - A TYPO3 Documentation Project's Configuration File
# Information about Settings.cfg:
# https://docs.typo3.org/typo3cms/HowToDocument/GeneralConventions/DirectoryFilenames.html#settings-cfg
#
# About Syntax:
# See https://docs.python.org/2/library/configparser.html
#
# Attention:
# Only " ;" can start an inline comment.
# This is: blank PLUS semicolon!
#
# #####
[general]
; endless list of all of the general simple settings
; you can use in 'conf.py'
project = Extensionname (Title Of Project)
version = 1.2
release = 1.2.3
t3author = My Authorname
copyright = since 1970 by My Authorname
description = Short sample description in one longer sentence or short paragraph.
It is mainly used for the PDF, Manpage and Techinfo version of this document.
What is this documentation about? Lorem ipsum: Explain to you how all this
mistaken idea of denouncing pleasure and praising pain was born and it will
give you a complete account of the system, and expound the actual teachings
of the great explorer of the truth, the master-builder of human happiness.
[html_theme_options]
; for theme t3SphinxThemeRtd
# NOTE: Fill in YOUR values in the following!
github_branch = latest
github_commit_hash =
github_repository = TYPO3-Documentation/TYPO3CMS-Example-ExtensionManual
github_revision_msg =
github_sphinx_locale =
# project_contact = documentation@typo3.org
project_contact =
# project_discussions= http://...
project_discussions =
# project_home =
project_home =
# project_issues = https://github.com/TYPO3-Documentation/TYPO3CMS-Example-ExtensionManual/issues
project_issues =
# project_repository = https://github.com/TYPO3-Documentation/TYPO3CMS-Example-ExtensionManual
project_repository =
use_opensearch =
[intersphinx_mapping]
; Comment out what you don't use.
; Uncomment only what you actually use in crossreferencing!
# t3api = https://typo3.org/api/typo3cms/
# t3cgl = https://docs.typo3.org/typo3cms/CodingGuidelinesReference/
# t3coreapi = https://docs.typo3.org/typo3cms/CoreApiReference/
# t3editors = https://docs.typo3.org/typo3cms/EditorsTutorial/
# t3extbasebook = https://docs.typo3.org/typo3cms/ExtbaseFluidBook/
# t3fal = https://docs.typo3.org/typo3cms/FileAbstractionLayerReference/
# t3inside = https://docs.typo3.org/typo3cms/InsideTypo3Reference/
# t3install = https://docs.typo3.org/typo3cms/InstallationGuide/
# t3l10n = https://docs.typo3.org/typo3cms/FrontendLocalizationGuide/
# t3security = https://docs.typo3.org/typo3cms/SecurityGuide/
# t3services = https://docs.typo3.org/typo3cms/Typo3ServicesReference/
# t3skinning = https://docs.typo3.org/typo3cms/SkinningReference/
# t3start = https://docs.typo3.org/typo3cms/GettingStartedTutorial/
# t3tca = https://docs.typo3.org/typo3cms/TCAReference/
# t3templating = https://docs.typo3.org/typo3cms/TemplatingTutorial/
# t3ts45 = https://docs.typo3.org/typo3cms/TyposcriptIn45MinutesTutorial/
# t3tsconfig = https://docs.typo3.org/typo3cms/TSconfigReference/
t3tsref = https://docs.typo3.org/typo3cms/TyposcriptReference/
# t3tssyntax = https://docs.typo3.org/typo3cms/TyposcriptSyntaxReference/
.. include:: ../Includes.txt
.. _support:
=======
Support
=======
Do you give paid or unpaid support for your extension? Add information here how to get
support. Maybe there is a Slack channel for your extension. Mention it here.
.. include:: ../Includes.txt
.. _todo:
==========
To-Do list
==========
Give a link pointing to a roadmap.
Alternatively, you can add a list of things you want to add or fix in this chapter
or give a vision about where the extension is heading.
.. include:: ../Includes.txt
.. _user-manual:
============
Users Manual
============
Target group: **Editors**
Here should be described how to use the extension from the editor perspective.
- How does it work?
- works well when doing this.
- does not work so well when doing that
but we can live with it.
- **mind indentation when nesting lists**.
- How to install the plugin on a web page?
- What options are available?
Language should be non-technical, explaining, using small examples.
Don't use to many acronyms unless they have been explained.
Don't be confusing by putting information targeting administrators.
.. tip::
Take a break from time to time.
Admonitions should be used to warn the users about potential
pitfalls, attract their attention to important elements
or just add some notes for for information (further reading,
for example).
.. important::
Remember to always say "please" when asking your software to
do something.
Provide screenshots as needed for making things clear. When creating
screenshots, try using the `Introduction Package <http://demo.typo3.org/>`_
as a neutral TYPO3 CMS instance.
.. figure:: ../Images/UserManual/BackendView.png
:width: 500px
:alt: Backend view
Default Backend view (caption of the image)
.. _user-faq:
FAQ
===
Possible subsection: FAQ
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment