Commit 5d176517 authored by Carsten  Rose's avatar Carsten Rose
Browse files

Documentation: added Sphinx Documentation

parent 40a4451b
.. ==================================================
.. FOR YOUR INFORMATION
.. --------------------------------------------------
.. -*- coding: utf-8 -*- with BOM.
.. include:: ../Includes.txt
.. _admin-manual:
Administrator Manual
====================
Describes how to manage the extension from an administrator’s point of
view. That relates to Page/User TSconfig, permissions, configuration
etc., which administrator level users have access to.
Language should be non/semi-technical, explaining, using small
examples.
Target group: **Administrators**
Installation
------------
How should the extension be set up? E.g. is there a static template to include?
.. figure:: ../Images/AdministratorManual/ExtensionManager.png
:width: 500px
:alt: Extension Manager
Extension Manager (caption of the image)
List of extensions within the Extension Manager also shortend as "EM" (legend of the image)
FAQ
^^^
Possible subsection: FAQ
.. ==================================================
.. 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
.. ==================================================
.. FOR YOUR INFORMATION TEST
.. --------------------------------------------------
.. -*- coding: utf-8 -*- with BOM.
.. include:: Includes.txt
.. _start:
=============================================================
QFQ Extension
=============================================================
.. only:: html
:Classification:
extension_key
:Version:
|release|
:Language:
en
:Description:
enter description.
:Keywords:
comma,separated,list,keywords
:Copyright:
2016
:Author:
Rafael Ostertag
:Email:
author@example.com
: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
:titlesonly:
Introduction/Index
UsersManual/Index
AdministratorManual/Index
Links
.. ==================================================
.. FOR YOUR INFORMATION
.. --------------------------------------------------
.. -*- coding: utf-8 -*- with BOM.
.. include:: ../Includes.txt
What does it do?
================
First of all, if you have any idea how this template can be improved, please, drop a note to our team_. Documentation is written in reST format. Please, refer to Help writing reStructuredText to get some insight regarding syntax and existing reST editors on the market.
.. _team: https://forge.typo3.org/projects/typo3v4-official_extension_template/issues
Here should be given a brief overview of the extension. What does it do? What problem does it solve? Who is interested in this? Basically the document includes everything people need to know to decide, if they should go on with this extension.
.. 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)
.. ==================================================
.. FOR YOUR INFORMATION
.. --------------------------------------------------
.. -*- coding: utf-8 -*- with BOM.
.. include:: Includes.txt
.. _links:
Links
-----
:TER:
https://typo3.org/extensions/repository/view/<extension key>
:Bug Tracker:
https://forge.typo3.org/projects/extension-<extension key>/issues
:Git Repository:
https://github.com/<username>/<extension key>
:Contact:
`@<username> <https://twitter.com/your-username>`__
.. ==================================================
.. FOR YOUR INFORMATION
.. --------------------------------------------------
.. -*- coding: utf-8 -*- with BOM.
.. include:: ../Includes.txt
.. _start:
=============================================================
QFQ Extension (Deutsch)
=============================================================
.. only:: html
:Klassifikation:
extension_key
:Version:
|release|
:Sprache:
de
:Beschreibung:
Geben Sie eine Beschreibung ein.
:Schlüsselwörter:
komma-getrennte,Liste,von,Schlüsselwörtern
:Copyright:
2016
:Autor:
Rafael Ostertag
:E-Mail:
author@example.com
:Lizenz:
Dieses Dokument wird unter der Open Content License, siehe
http://www.opencontent.org/opl.shtml veröffentlicht.
:Gerendert:
|today|
Der Inhalt dieses Dokuments bezieht sich auf TYPO3,
ein GNU/GPL CMS-Framework auf `www.typo3.org <https://typo3.org/>`__.
**Inhaltsverzeichnis**
.. toctree::
:maxdepth: 3
:titlesonly:
.. Introduction/Index
.. UsersManual/Index
.. AdministratorManual/Index
How to translate
================
This directory contains the German translation of your documentation.
This is a complete Sphinx project but you may reuse assets from the
main documentation under Documentation/.
If you plan to translate your documentation to German, you should
rename this directory and remove the suffix ".tmpl":
Localization.de_DE.tmpl -> Localization.de_DE
As this file is not needed either, feel free to delete it as well.
Supported languages
===================
Please visit http://sphinx-doc.org/latest/config.html#intl-options for a
list of languages supported by Sphinx.
Please note however that TYPO3 is using locales so you may need to
extend the language code from Sphinx into a proper locale to be used
by TYPO3.
# This is the project specific Settings.yml file.
# Place Sphinx specific build information here.
# Settings given here will replace the settings of 'conf.py'.
---
conf.py:
copyright: 2016
project: QFQ Extension (Deutsch)
version: 0.1
release: 0.1.0
latex_documents:
- - Index
- qfq.tex
- QFQ Extension
- Rafael Ostertag
- manual
latex_elements:
papersize: a4paper
pointsize: 10pt
preamble: \usepackage{typo3}
...
.. ==================================================
.. FOR YOUR INFORMATION
.. --------------------------------------------------
.. -*- coding: utf-8 -*- with BOM.
.. include:: ../Includes.txt
.. _start:
=============================================================
QFQ Extension (Français)
=============================================================
.. only:: html
:Classification:
extension_key
:Version:
|release|
:Langue:
fr
:Description:
entrez une description.
:Mots-clés:
list,mots-clés,séparés,par,virgules
:Copyright:
2016
:Auteur:
Rafael Ostertag
:E-mail:
author@example.com
:Licence:
Ce document est publié sous la licence de contenu libre
disponible sur http://www.opencontent.org/opl.shtml
:Généré:
|today|
Le contenu de ce document est en relation avec TYPO3,
un CMS/Framework GNU/GPL disponible sur `www.typo3.org <https://typo3.org/>`__.
**Sommaire**
.. toctree::
:maxdepth: 3
:titlesonly:
.. Introduction/Index
.. UsersManual/Index
.. AdministratorManual/Index
How to translate
================
This directory contains the French translation of your documentation.
This is a complete Sphinx project but you may reuse assets from the
main documentation under Documentation/.
If you plan to translate your documentation to French, you should
rename this directory and remove the suffix ".tmpl":
Localization.fr_FR.tmpl -> Localization.fr_FR
As this file is not needed either, feel free to delete it as well.
Supported languages
===================
Please visit http://sphinx-doc.org/latest/config.html#intl-options for a
list of languages supported by Sphinx.
Please note however that TYPO3 is using locales so you may need to
extend the language code from Sphinx into a proper locale to be used
by TYPO3.
# This is the project specific Settings.yml file.
# Place Sphinx specific build information here.
# Settings given here will replace the settings of 'conf.py'.
---
conf.py:
copyright: 2016
project: QFQ Extension (Français)
version: 0.1
release: 0.1.0
latex_documents:
- - Index
- qfq.tex
- QFQ Extension
- Rafael Ostertag
- manual
latex_elements:
papersize: a4paper
pointsize: 10pt
preamble: \usepackage{typo3}
...
# This is the project specific Settings.yml file.
# Place Sphinx specific build information here.
# Settings given here will replace the settings of 'conf.py'.
---
conf.py:
copyright: 2016
project: QFQ Extension
version: 0.1
release: 0.1.0
latex_documents:
- - Index
- qfq.tex
- QFQ Extension
- Rafael Ostertag
- manual
latex_elements:
papersize: a4paper
pointsize: 10pt
preamble: \usepackage{typo3}
intersphinx_mapping:
t3tsref:
- http://docs.typo3.org/typo3cms/TyposcriptReference/
- null
t3start:
- http://docs.typo3.org/typo3cms/GettingStartedTutorial/
- null
t3editors:
- http://docs.typo3.org/typo3cms/EditorsTutorial/
- null
...
.. ==================================================
.. FOR YOUR INFORMATION
.. --------------------------------------------------
.. -*- coding: utf-8 -*- with BOM.
.. include:: ../Includes.txt
.. _users-manual:
Users manual
============
Documentation of how to use the extension, how it works, how to apply it, if it's a website plugin.
Language should be non-technical, explaining, using small examples. Don't use to many acronyms unless they have been explained.
Examples: For the "News" plugin this would be a manual showing how to create the news items, explaining the options etc.
Provide screenshots of a neutral Backend such as the Backend of the Introduction Package for instance. Have in mind that the User manual could possibly be re-used in a larger documentation compilation, for example when a company generates a documentation for its client.
Target group: **Users**
.. figure:: ../Images/UserManual/BackendView.png
:width: 500px
:alt: Backend view
Default Backend view (caption of the image)
The Backend view of TYPO3 after the user has clicked on module "Page". (legend of the image)
Link to official documentation
------------------------------
Sphinx makes it easy to link to official TYPO3 documentation:
- :ref:`TYPO3 Tutorial for Editors <t3editors:start>`
- :ref:`Getting Started Tutorial <t3start:start>`
and you may even link to a very specific chapter explaining how to :ref:`create a browser condition <t3tsref:condition-browser>` within the TypoScript Reference.
For a complete reference of available cross-link prefixes, please consult file ``_make/conf.py``.
FAQ
^^^
Possible subsection: FAQ
# You can set these variables from the command line.
SPHINXOPTS = -c . -a -E -w ./_not_versioned/warnings.txt
SPHINXBUILD = sphinx-build
PAPER = a4
BUILDDIR = build
# User-friendly check for sphinx-build
ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
endif
# Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) ..
# the i18n builder cannot share the environment and doctrees with the others
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) ..
.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
help:
@echo "Please use \`make <target>' where <target> is one of"
@echo " html to make standalone HTML files"
@echo " dirhtml to make HTML files named index.html in directories"
@echo " singlehtml to make a single large HTML file"
@echo " pickle to make pickle files"
@echo " json to make JSON files"
@echo " htmlhelp to make HTML files and a HTML help project"
@echo " qthelp to make HTML files and a qthelp project"
@echo " devhelp to make HTML files and a Devhelp project"
@echo " epub to make an epub"
@echo " pdf to make PDF using rst2pdf"
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
@echo " latexpdf to make LaTeX files and run them through pdflatex"
@echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
@echo " text to make text files"
@echo " man to make manual pages"
@echo " texinfo to make Texinfo files"
@echo " info to make Texinfo files and run them through makeinfo"
@echo " gettext to make PO message catalogs"
@echo " changes to make an overview of all changed/added/deprecated items"
@echo " xml to make Docutils-native XML files"
@echo " pseudoxml to make pseudoxml-XML files for display purposes"
@echo " linkcheck to check all external links for integrity"
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
clean:
rm -rf $(BUILDDIR)/*
html:
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
dirhtml:
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
singlehtml:
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
@echo
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
pickle:
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
@echo
@echo "Build finished; now you can process the pickle files."
json:
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
@echo
@echo "Build finished; now you can process the JSON files."
htmlhelp:
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
@echo
@echo "Build finished; now you can run HTML Help Workshop with the" \
".hhp project file in $(BUILDDIR)/htmlhelp."
qthelp:
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
@echo
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
".qhcp project file in $(BUILDDIR)/qthelp, like this:"
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/QFQ Extension.qhcp"
@echo "To view the help file:"
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/QFQ Extension.qhc"
devhelp:
$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
@echo
@echo "Build finished."
@echo "To view the help file:"
@echo "# mkdir -p $$HOME/.local/share/devhelp/QFQ Extension"
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/QFQ Extension"
@echo "# devhelp"
epub:
$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
@echo
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
pdf:
$(SPHINXBUILD) -b pdf $(ALLSPHINXOPTS) $(BUILDDIR)/pdf
@echo
@echo "Build finished. The PDF is in $(BUILDDIR)/pdf."
latex:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
@echo "Run \`make' in that directory to run these through (pdf)latex" \
"(use \`make latexpdf' here to do that automatically)."
latexpdf:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo "Running LaTeX files through pdflatex..."
$(MAKE) -C $(BUILDDIR)/latex all-pdf
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
latexpdfja:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo "Running LaTeX files through platex and dvipdfmx..."
$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
text:
$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
@echo
@echo "Build finished. The text files are in $(BUILDDIR)/text."
man:
$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
@echo
@echo "Build finished. The manual pages are in $(BUILDDIR)/man."