diff --git a/Documentation/Basics/Index.rst b/Documentation/Basics/Index.rst new file mode 100644 index 00000000..18c04cbe --- /dev/null +++ b/Documentation/Basics/Index.rst @@ -0,0 +1,10 @@ +:orphan: + +====== +Basics +====== + +.. menu:: + :glob: + + * diff --git a/Documentation/Basics/RstCheatSheet.rst b/Documentation/Basics/RstCheatSheet.rst new file mode 100644 index 00000000..d3da2e8d --- /dev/null +++ b/Documentation/Basics/RstCheatSheet.rst @@ -0,0 +1,226 @@ +:navigation-title: ReST Cheat Sheet +.. include:: /Includes.rst.txt +.. _writing-rest-introduction: +.. _Formatting-with-reST: +.. _rest-quick-start: +.. _rest-cheat-sheet: + +=============================================================== +ReST Cheat sheet: Using reStructuredText in TYPO3 Documentation +=============================================================== + +.. contents:: Cheat Sheet + +.. _rest-cheat-sheet-headlines-anchors: + +Headlines and Anchors +===================== + +Each reST document must have a title. It is overlined and underlined like this: + +.. code-block:: rst + + .. _rest-cheat-sheet: + + ============================= + Cheat sheet: reStructuredText + ============================= + + Some text. + + .. _h2-headline: + + H2 Headline + =========== + + Lorem Ipsum + + .. _h3-headline: + + H3 Headline + ----------- + +There are more :ref:`levels of headlines ` + +.. _rest-cheat-sheet-contents: + +Contents menu +============= + +If you use more then one headlines consider to provide a contents menu. It +also allows your users to collapse all sections and only open the one they are +reading: + +.. code-block:: rst + + .. contents:: + +Additional options are possible: :ref:`contents menu options `. + +.. _rest-cheat-sheet-links: + +References and linking +====================== + +References to documentation from the TYPO3 world should be copied from the wizard: + +.. figure:: /_Images/link-headlines.png + + Hover over a headline to see if it is linkable, then click the link icon + +They then look like this: + +.. code-block:: rst + + :ref:`Cheat sheet: reStructuredText ` + +External links can be copied into the document they will be auto detected. Or +the standard reST Syntax can be used: + +.. code-block:: rst + + See also https://www.typo3.org or `the TER `. + +There are special links for composer packages and PHP classes (linking to the API): + +.. code-block:: rst + + Install :composer:`typo3/cms-seo` to listen to event + :php:`\TYPO3\CMS\Seo\Event\ModifyUrlForCanonicalTagEvent`. + +There is a dedicated chapter on links and references in reST: :ref:`links`. + +.. _rest-cheat-sheet-code-blocks: + +Code blocks +=========== + +Short code blocks can be inserted directly into a reST file: + +.. code-block:: rst + + .. code-block:: php + :caption: EXT:my_extension/ext_localconf.php + + defined('TYPO3') or die(); + +Longer code blocks should be put into a file starting with an underscore and +included: + +.. code-block:: rst + + .. literalinclude:: /snippets/_HelloWorld.php + :caption: EXT:my_extension/Classes/WorldDominance/HelloWorld.php + +All :ref:`options of code blocks ` can also be +applied to literal includes. + +.. _rest-cheat-sheet-confvals: + +Configuration values (confvals) +=============================== + +Configuration values can be defined like this: + +.. code-block:: rst + + .. confval:: label + :name: some-unique-label + :required: true + :type: string or LLL reference + :default: "abc" + + The name of the field as shown in the form. + +Configuration values can have custom properties and displayed in special +confval menues: :ref:`rest-confval`. + +.. _rest-cheat-sheet-images: + +Figures and Images +================== + +.. code-block:: rst + + .. figure:: /_Images/a4.jpg + :alt: some image + + The caption of the image + +* :ref:`Images in reST ` +* :ref:`Guidelines for creating images ` + + +.. _rest-cheat-sheet-lists: + +Lists, ordered and unordered +============================ + +.. code-block:: rst + + * unordered + * Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam + nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, + sed diam voluptua. + * list + + #. ordered + #. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam + nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, + sed diam voluptua. + #. list + +More about :ref:`Lists `. + +.. _rest-cheat-sheet-inline: + +Inline text roles +================= + +.. code-block:: rst + + *italic text*, **bold text**, `general code` :typoscript:`page = PAGE` + :php:`\TYPO3\CMS\Seo\Event\ModifyUrlForCanonicalTagEvent` :guilabel:`Web > Page` + :composer:`typo3/cms-typo3` + +Looks like this: + +*italic text*, **bold text**, `general code` :typoscript:`page = PAGE` +:php:`\TYPO3\CMS\Seo\Event\ModifyUrlForCanonicalTagEvent` :guilabel:`Web > Page` +:composer:`typo3/cms-typo3` + +More: :ref:`rest-bold-italic`. + +.. _rest-cheat-sheet-comments: + +Comments +======== + +Comments can be written like this: + +.. code-block:: rst + + .. this is a comment + .. with another line + +Or like this: + +.. code-block:: rst + + .. this is a comment + with another line + +.. _rest-cheat-sheet-escape: + +Escape characters +================= + +If you want to use a character, which would create some special reST markup, +with its normal meaning, you must escape it with a prepended "\". + +For example surrounding text with "*" signs normally makes it show up in italics. By +escaping the special characters "*" you make the stars normal text characters: + +.. code-block:: rst + + \*non-italic\* diff --git a/Documentation/Howto/Index.rst b/Documentation/Howto/Index.rst new file mode 100644 index 00000000..b7bf8e50 --- /dev/null +++ b/Documentation/Howto/Index.rst @@ -0,0 +1,10 @@ +:orphan: + +====== +How to +====== + +.. menu:: + :glob: + + * diff --git a/Documentation/Howto/WritingReST/BasicRestSyntax.rst b/Documentation/Howto/WritingReST/BasicRestSyntax.rst deleted file mode 100644 index 8834e9aa..00000000 --- a/Documentation/Howto/WritingReST/BasicRestSyntax.rst +++ /dev/null @@ -1,85 +0,0 @@ -.. include:: /Includes.rst.txt -.. index:: reST; Syntax -.. _basic-rest-syntax: - -============================= -Basic reStructuredText syntax -============================= - -The `.rst` files are written in reStructuredText (reST) format. They -contain text with additional markup. - - -.. index:: reST; Paragraphs - -Paragraphs -========== - -New paragraphs in the output are created by an empty line -between two paragraphs in your reST file: - -.. code-block:: rst - - This is a paragraph. - - This is another paragraph. - - -.. index:: reST; Comments - -Comments -======== - -Comments can be written like this: - -.. code-block:: rst - - .. this is a comment - .. with another line - -Or like this: - -.. code-block:: rst - - .. this is a comment - with another line - - -.. index:: reST; Indentation - -Indentation -=========== - -In reST, the indentation of a block of lines is often important. The exact number of spaces, -which are used to indent a block of text, does not matter. But what does matter, is that all lines -of the block are indented with exactly the same number of spaces. - -We use the convention of 4 spaces per indenting level (see :ref:`cgl-indenting`). - -Let's look at an example: - -The following directive inserts an image in the rendered page. All lines beginning with line -two must be indented to the same leve. The convention is to use 4 spaces for one -level of indentation. - -.. code-block:: rst - - .. image:: someimage.png - :class: with-border with-shadow - :alt: Textual alternative to the image - - -.. index:: reST; Escape characters - -Escape characters -================= - -If you want to use a character, which would create some special reST markup, -with its normal meaning, you must escape it with a prepended "\". - -For example surrounding text with "*" signs normally makes it show up in italics. By -escaping the special characters "*" you make the stars normal text characters: - -.. code-block:: rst - - \*non-italic\* diff --git a/Documentation/Howto/WritingReST/CheatSheet.rst b/Documentation/Howto/WritingReST/CheatSheet.rst deleted file mode 100644 index 2b9d854c..00000000 --- a/Documentation/Howto/WritingReST/CheatSheet.rst +++ /dev/null @@ -1,756 +0,0 @@ -.. include:: /Includes.rst.txt - -.. ------------------------------------------------------------------------ - header label: You can use this to create - cross-references: To link to the next section, use :ref:`rest-cheat-sheet` - or :ref:`rest-cheat-sheet` from another manual - ------------------------------------------------------------------------- - - -.. --------------------------------------------------------- - header: Use (over and) underline to mark a text as header - --------------------------------------------------------- - -.. index:: reST; Cheat sheet -.. _rest-cheat-sheet: - -============================= -Cheat sheet: reStructuredText -============================= - -:ref:`Headlines ` -========================================= - -Every reST (.rst) file should use these underlining styles. In reST, you can use different -styles in any order you want. These are our conventions for TYPO3 documentation. - -.. code-block:: rst - :linenos: - - ======== - DocTitle - ======== - - Then use underlining only: - - .. _header1: - - Header 1 - ======== - - Header 1.1 - ---------- - - Header 1.1.1 - ~~~~~~~~~~~~ - - Header 1.1.1.1 - """""""""""""" - -* line 1-3: This is the doc title. Every .rst file should have one. -* line 7: header label. This can be used for cross-referencing to this section: - - .. code-block:: rst - - :ref:`header1` - -* 9-10: Header level 1 -* etc. - -.. seealso:: - * :ref:`Headlines-and-sections` - * :ref:`explicit-link-targets` - - -.. _cheat-sheet-links: - -:ref:`Links ` -========================================= - - -.. index:: reST; External links -.. _cheat-sheet-external-links: - -External links --------------- - -method 1: - -.. code-block:: rst - - `anchor text `__ - - Check out more information on `t3o `__. - -(with one or two underscores at the end, if in doubt, use two) - -method 2: "External Hyperlink Targets": - -.. code-block:: rst - - Check out more information on t3o_ - - _t3o: https://typo3.org - -This may be more convenient if you use a link several times. - - -.. index:: - reST; Cross references - reST roles; ref -.. _cheat-sheet-intersphinx: - -Cross references ----------------- - -When linking within docs.typo3.org, you should use this method of cross-referencing. - -Use it to link to a section in this manual: - -.. code-block:: rst - - :ref:`intersphinx` - -A section with the label **intersphinx** must exist! It is placed before the header: - -.. code-block:: rst - - .. _intersphinx: - - Intersphinx - =========== - -Or, when cross-referencing to other manuals: - -.. code-block:: rst - - :ref:`shortcut:label` - -:ref:`intersphinx` - - -When you are linking to another manual, make sure the -shortcut (here: "h2document") is included in :ref:`settings-guides-xml`: - -.. code-block:: none - - - - ... - -We use the same conventions for naming the shortcuts in :file:`Settings.cfg`, -see :ref:`settings-cfg`. Not used manuals are commented out. - - -.. tip:: - - This is a cool feature, where reST & Sphinx shines: Even when a section is - moved to another page (which effectively changes the URL), the link will still work! - -.. t3-field-list-table:: - :header-rows: 1 - - - :Anchor: - :ThisManual: Link to: Same manual - :OtherManual: Link to: Other manual - - - :Anchor: **Explicit** anchor text - :ThisManual: ``:ref:`Cross Referencing ``` - :OtherManual: ``:ref:`Cross Referencing ``` - - - :Anchor: **Automatic** anchor text - :ThisManual: ``:ref:`intersphinx``` - :OtherManual: ``:ref:`t3docwrite:intersphinx``` - -.. index:: reST; Preventing links -.. _cheat-sheet-preventing-links: - -Preventing links ----------------- - -Prevent unintentional linking of simple URLs with the :code:`:samp:` directive: - -.. code-block:: rst - - The TYPO3 backend can be accessed via :samp:`https://example.org/typo3` .. - -and emphasize parts of the URL with curly braces: - -.. code-block:: rst - - The *route* is the "speaking URL" as a whole without the domain part, - for example :samp:`https://example.org/{}`. - -.. index:: reST; Hypothetical domains -.. _cheat-sheet-hypothetical-domains: - -Hypothetical domains --------------------- - -If the domain name of an URL does not matter, but serves as a placeholder, -choose from this list of dummy domains – in this order: - -1. :samp:`https://example.org` -2. :samp:`https://example.com` -3. :samp:`https://example.net` - -and use for explicit mention of the local development context: - -4. :samp:`https://example.localhost`. - -For further dummy domains use subdomains of the domains listed above such as - -- :samp:`https://staging.example.org` -- :samp:`https://production.example.org`. - -.. seealso:: - - * :ref:`link-targets-explanation` (labels) - * :ref:`intersphinx` - * :ref:`settings-cfg` - - - -.. index:: - reST; Lists - reST; Bullet lists - -:ref:`Lists ` -========================= - -**How it looks:** - -To create a bullet list: - -* add a blank line before and after the list -* indent the list item text by 4 spaces - including the item sign -* to create a nested list: - - * indent the items by 4 spaces (left-align with parent item text) - * apply rules of parent list (blank lines, item text indentation, ..) - -More text. - -Source: - -.. code-block:: rst - - To create a bullet list: - - * add a blank line before and after the list - * indent the list item text by 4 spaces - including the item sign - * to create a nested list: - - * indent the items by 4 spaces (left-align with parent item text) - * apply rules of parent list (blank lines, item text indentation, ..) - - More text. - - -.. index:: reST; Numbered lists - -:ref:`numbered-lists` -===================== - -**How it looks:** - -To create a numbered list: - -#. add a blank line before and after the list -#. indent the list item text by 4 spaces - including the item sign -#. to create a nested list: - - #. indent the items by 4 spaces (left-align with parent item text) - #. apply rules of parent list (blank lines, item text indentation, ..) - -More text. - -Source: - -.. code-block:: rst - - To create a numbered list: - - #. add a blank line before and after the list - #. indent the list item text by 4 spaces - including the item sign - #. to create a nested list: - - #. indent the items by 4 spaces (left-align with parent item text) - #. apply rules of parent list (blank lines, item text indentation, ..) - - More text. - - -.. index:: reST; Code blocks - -:ref:`Code Blocks ` -===================================================================== - -.. important:: - - Use syntactically correct code in your code blocks. - - -.. index:: reST directives; code-block - -Code block directive --------------------- - -**How it looks:** - -.. code-block:: php - - $a = 'hello'; - $b = 'something'; - -Source: - -.. code-block:: rst - :linenos: - - .. code-block:: php - - $a = 'hello'; - $b = 'something'; - -This uses the **directive** "code-block" (line 1) - -.. important:: - - Make sure to indent correctly. The lines of the code-block (line 3+) - must be indented (4 spaces). - -Placeholders ------------- - -Use the `Backus-Naur form `__ like `` for placeholders in code and -URLs. - -Examples: - -#. :php:`class Controller extends ActionController` -#. `typo3/sysext/core/bin/typo3 impexp:import ` -#. :samp:`https://example.org/typo3/main?token=` - -For XML and HTML, use the comment tag :html:``. - - -.. index:: reST roles - -:ref:`Inline code, text roles ` -=========================================== - -For inline code or for other semantic markup of special texts, use text roles. - -**How it looks:** - -#. :php:`$result = $a + 23;` (PHP snippet) -#. :typoscript:`lib.hello.value = Hello World!` (TypoScript snippets) -#. :file:`/etc/passwd` (file) -#. :bash:`bin/typo3 cleanup:flexforms` (shell) -#. :sql:`tt_content.pi_flexform` (SQL) -#. :xml:`` (XML) -#. :kbd:`ctrl` + :kbd:`s` (keyboard strokes) - -Source: - -.. code-block:: rst - :linenos: - - :php:`$result = $a + 23;` - :typoscript:`lib.hello.value = Hello World!` - :file:`/etc/passwd` - :bash:`bin/typo3 cleanup:flexforms` (shell) - :sql:`tt_content.pi_flexform` (SQL) - :xml:`` (XML) - :kbd:`ctrl` + :kbd:`s` - - -.. index:: - reST; Bold - reST; Italic - -:ref:`Bold & italic ` -======================================= - -**How it looks:** - -Normal text, **bold text** and *italic text*. - -Source: - -.. code-block:: rst - - Normal text, **bold text** and *italic text*. - - -.. index:: - reST; Images - reST directives; image - -:ref:`Images ` -=========================== - -**How it looks:** - -.. image:: /_Images/a4.jpg - :class: with-shadow - -Source: - -.. code-block:: rst - - .. image:: /_Images/a4.jpg - :class: with-shadow - -Another example: - -.. code-block:: rst - - .. image:: /_Images/a4.jpg - :class: with-shadow - :target: https://typo3.org - :alt: alt text - :width: 100px - -.. seealso:: - - * :ref:`images` - - -.. index:: - reST; YouTube videos - reST directives; youtube - -:ref:`YouTube videos ` -=============================== - -**How it looks:** - -.. youtube:: wNxO-aXY5Yw - -Source: - -.. code-block:: rst - - .. youtube:: wNxO-aXY5Yw - - -.. index:: - reST; Styled numbered lists - reST classes; bignums - -:ref:`Styled numbered lists ` -======================================= - -This is often used, for a Quick Start section, involving a few numbered steps: - -With Big Numbers ----------------- - -This is an example with a code block (:rst:`::`) embedded in the sections. - -**How it looks:** - -.. rst-class:: bignums - -1. Embed an image - - Source: - - .. code-block:: rst - - /_Images/a4.jpg - :class: with-shadow - -2. Two - - Do something else ... - -Source: - -.. code-block:: rst - - .. rst-class:: bignums - - 1. Embed an image - - Source: - - .. code-block:: rst - - .. image: some_image.png - :class: with-shadow - - 2. Two - - Do something else ... - - -With Big Numbers XXL --------------------- - -**How it looks:** - -.. rst-class:: bignums-xxl - -1. Embed an image - - Source: - - .. code-block:: rst - - /_Images/a4.jpg - :class: with-shadow - -2. Two - - Do something else ... - -Source: - -.. code-block:: rst - - .. rst-class:: bignums-xxl - - 1. Embed an image - - Source: - - .. code-block:: rst - - .. image: some_image.png - :class: with-shadow - - 2. Two - - Do something else ... - - -:ref:`Configuration values ` (confval) -==================================================== - -See also: :ref:`rest-confval`. - -**How it looks:** - -.. confval:: title - :name: unique-title - :required: true - :type: string or LLL reference - :Scope: Display - :Path: $GLOBALS > TCA > [table] > columns > [field] - - The name of the field as shown in the form. - -Source: - -.. code-block:: rst - - .. confval:: title - :name: unique-title - :required: true - :type: string or LLL reference - :Scope: Display - :Path: $GLOBALS > TCA > [table] > columns > [field] - - The name of the field as shown in the form. - - -:ref:`PHP domain ` -================================== - -**How it looks:** - -.. php:namespace:: Vendor\MyExtension - -.. php:class:: DateTime - - Datetime class - - .. php:method:: setDate($year, $month, $day) - - Set the date. - - :param int $year: The year. - :param int $month: The month. - :param int $day: The day. - :returns: Either false on failure, or the datetime object for method chaining. - -Source: - -.. code-block:: rst - - .. php:namespace:: Vendor\MyExtension - - .. php:class:: DateTime - - Datetime class - - .. php:method:: setDate($year, $month, $day) - - Set the date. - - :param int $year: The year. - :param int $month: The month. - :param int $day: The day. - :returns: Either false on failure, or the datetime object for method chaining. - - -.. index:: reST; Admonitions - -:ref:`Tips, hints, important ` (Admonitions) -============================================================== - -.. --------------------------------------------------------------- - tip: This directive will display the following indented text as - text with a green box (as styled by our sphinx template). - --------------------------------------------------------------- - -Visit :ref:`rest-admonitions` to see the available admonitions. - -**How it looks:** - -.. tip:: - - To look at the reST source of this rendered page, scroll to the top - and click on :guilabel:`View source`. - -Source: - -.. code-block:: rst - - .. tip:: - - To look at the reST source of this rendered page, scroll to the bottom - and click on "View page source". - - -:ref:`Cards ` -========================= - -**How it looks:** - -.. container:: row m-0 p-0 - - .. container:: col-md-6 pl-0 pr-3 py-3 m-0 - - .. container:: card px-0 h-100 - - .. rst-class:: card-header h3 - - .. rubric:: :ref:`Pages ` - - .. container:: card-body - - The Page Management Guide introduces TYPO3's Page Tree and explains how pages are created and managed. - - .. container:: card-footer pb-0 - - .. rst-class:: horizbuttons-striking-m - - - `11 `__ - -Source: - -.. code-block:: rst - - .. container:: row m-0 p-0 - - .. container:: col-md-6 pl-0 pr-3 py-3 m-0 - - .. container:: card px-0 h-100 - - .. rst-class:: card-header h3 - - .. rubric:: :ref:`Pages ` - - .. container:: card-body - - The Page Management Guide introduces TYPO3's Page Tree and explains how pages are created and managed. - - .. container:: card-footer pb-0 - - .. rst-class:: horizbuttons-striking-m - - - `11 `__ - - -:ref:`Tabs ` -======================= - -**How it looks:** - -.. tabs:: - - .. group-tab:: bash - - .. code-block:: bash - - touch example-project-directory/public/FIRST_INSTALL - - .. group-tab:: powershell - - .. code-block:: powershell - - echo $null >> public/FIRST_INSTALL - -Source: - -.. code-block:: rst - - .. tabs:: - - .. group-tab:: bash - - .. code-block:: bash - - touch example-project-directory/public/FIRST_INSTALL - - .. group-tab:: powershell - - .. code-block:: powershell - - echo $null >> public/FIRST_INSTALL - -:ref:`Diagrams ` -=================================== - -**How it looks:** - -.. uml:: - :caption: Some Caption - - class -> otherClass : message - -Source: - -.. code-block:: rst - :caption: Documentation/SomeFile.rst - - .. uml:: - :caption: Some Caption - - class -> otherClass : message - - -:ref:`Sidebar ` -============================= - -Source / **How it looks**: - -.. sidebar:: reST content elements - - * :ref:`Cards ` - * :ref:`Tabs ` - * :ref:`Configuration values ` - -.. code-block:: rst - - .. sidebar:: reST content elements - - * :ref:`Cards ` - * :ref:`Tabs ` - * :ref:`Configuration values ` diff --git a/Documentation/Howto/WritingReST/Index.rst b/Documentation/Howto/WritingReST/Index.rst deleted file mode 100644 index cad68f63..00000000 --- a/Documentation/Howto/WritingReST/Index.rst +++ /dev/null @@ -1,37 +0,0 @@ -:navigation-title: Write ReST - -.. include:: /Includes.rst.txt -.. index:: - reStructuredText - reST -.. _Formatting-with-reST: -.. _format-sphinx: -.. _rest-quick-start: - -================ -reStructuredText -================ - -This chapter is an introduction and reference for writing documentation using -reStructuredText (also referred to as reST). - -It is recommended to read (or at least browse through) -the :ref:`writing-rest-introduction` and the general -:ref:`format-rest-cgl` first. - -Or, use the :ref:`rest-cheat-sheet`, which contains the most commonly used -markup on one page. - -We cannot cover every reST markup that is -available. For more information, see other resources, such as: - -* `reSTructuredText reference by Sphinx `__ -* `reSTructuredText introduction on docutils `__ -* `reStructuredText Markup Specification `__ - -.. toctree:: - :hidden: - - Introduction - BasicRestSyntax - CheatSheet diff --git a/Documentation/Howto/WritingReST/Introduction.rst b/Documentation/Howto/WritingReST/Introduction.rst deleted file mode 100644 index ae6505a0..00000000 --- a/Documentation/Howto/WritingReST/Introduction.rst +++ /dev/null @@ -1,116 +0,0 @@ -.. include:: /Includes.rst.txt - -.. _writing-rest-introduction: - -============ -Introduction -============ - -reStructuredText -================ - -The official documentation for TYPO3 uses reStructuredText (reST). The -file ending of reST files is :file:`.rst`. - -reStructuredText is a markup language for writing documentation. You can -edit the source files using plain text and add reST markup where needed. - -For example to create section headers, you use underlines: - -.. code-block:: rst - - ======== - Header 1 - ======== - - Header 1.1 - ========== - - some text - - Header 1.1.1 - ------------ - - some more text - - Header 1.2 - ========== - - -This will create a header "Header 1" on level 1 and headers "Header 1.1" -and "Header 1.2" on level 2 etc. The header level should reflect the structure -of the content. - -.. code-block:: none - - Header 1 - |-> Header 1.1 - |-> Header 1.1.1 - |-> Header 1.2 - -On the page you are looking at now, "Introduction" is a level 1 header and "reST", -"Sphinx" etc. are level 2 headers. - -The levels determine how the headers will be styled and also how they will be structured -in the menu in the sidepanel. - -.. index:: ! Sphinx - -Sphinx -====== - -While reStructuredText is the markup language, Sphinx is a suite of tools used to render -the documentation. Rendering in this context means that an output format such -as PDF or HTML is created from the source .rst files. - -We will not go into the exact definition here. For now, all you need to know -is that some of the markup you will be using is added on by Sphinx. -This is the case for some additional directives such as: - -* the :ref:`:ref: ` directive for cross-referencing -* the :ref:`toctree ` directive for creating table of contents (=toc) - and menus -* the :ref:`code-block ` directive for creating code blocks with syntax - highlighting. `code-block` is a Sphinx directive, while `code` - is a (native) reStructuredText directive. We commonly use `code-block`, - not `code`. - - -Additional information: - -* `Sphinx Markup Constructs `__ -* `What is the difference: reST, docutils, sphinx, readthedocs `__ (2016) - -.. index:: reST; Rendering - -Rendering -========= - -The documentation source files will later be rendered into the output format (HTML) on our -documentation server. The rendering is done automatically: If the -source files change, they are rerendered. - -Our headline example from above will look like this: - -.. image:: /_Images/rendered-headers.png - :class: with-shadow - - -Looking at the source -===================== - -Whenever you come across a documentation page on docs.typo3.org, you can look -at the source code by clicking on the :guilabel:`View source` at the top of a page. - -That way, you can see how it is done and compare the reST source with the -rendered version. - -.. image:: /_Images/view-page-source.png - :class: with-shadow - - -.. hint:: - - Look at the source code of this page now. - - diff --git a/Documentation/Index.rst b/Documentation/Index.rst index f3fec5b0..9dd88310 100644 --- a/Documentation/Index.rst +++ b/Documentation/Index.rst @@ -95,6 +95,7 @@ reStructuredText (reST). Basics/HowToGetHelp Basics/BasicPrinciples Basics/GeneralConventions/Index + Basics/RstCheatSheet .. toctree:: diff --git a/Documentation/Reference/GuidesXml.rst b/Documentation/Reference/GuidesXml.rst index 41034c92..1a5cab7e 100644 --- a/Documentation/Reference/GuidesXml.rst +++ b/Documentation/Reference/GuidesXml.rst @@ -533,7 +533,7 @@ of a manual. .. rubric:: Example: Set the preferred TYPO3 Core version to 11.5 At the time of writing the extension :t3ext:`news` is compatible with TYPO3 v11.5 - and v12.4. When :ref:`referencing ` Core manuals or + and v12.4. When :ref:`referencing ` Core manuals or extensions, we want the links to go automatically to version 11.5 of that reference or core extension. Therefore we set the preferred TYPO3 Core version to that value: diff --git a/Documentation/Reference/ReStructuredText/Index.rst b/Documentation/Reference/ReStructuredText/Index.rst index 9f858975..118824e2 100644 --- a/Documentation/Reference/ReStructuredText/Index.rst +++ b/Documentation/Reference/ReStructuredText/Index.rst @@ -5,9 +5,26 @@ .. _rest-reference: ========================== -reStructuredText Reference +reStructuredText reference ========================== +This chapter is an introduction and reference for writing documentation using +reStructuredText (also referred to as reST). + +It is recommended to read (or at least browse through) +the :ref:`writing-rest-introduction` and the general +:ref:`format-rest-cgl` first. + +Or, use the :ref:`rest-cheat-sheet`, which contains the most commonly used +markup on one page. + +We cannot cover every reST markup that is +available. For more information, see other resources, such as: + +* `reSTructuredText reference by Sphinx `__ +* `reSTructuredText introduction on docutils `__ +* `reStructuredText Markup Specification `__ + .. toctree:: :titlesonly: :glob: diff --git a/Documentation/Reference/ReStructuredText/Menus/HeadlinesAndSection.rst b/Documentation/Reference/ReStructuredText/Menus/HeadlinesAndSection.rst index ace22e85..577469dc 100644 --- a/Documentation/Reference/ReStructuredText/Menus/HeadlinesAndSection.rst +++ b/Documentation/Reference/ReStructuredText/Menus/HeadlinesAndSection.rst @@ -4,139 +4,100 @@ pair: reST; Headlines pair: reST; Titles pair: reST; Sections -.. _Headlines-and-sections: +.. _headlines-and-sections: ====================== -Headlines and sections +Headlines and Anchors ====================== -reStructuredText (reST) does not exactly have the notion of "headlines". Text -is split into "sections" instead. Those sections are identified by titles which -- in the end - appear as headlines as we know them. -**TYPO3** uses these conventions. +.. contents:: -1. Use underlining plus overlining with `===` for the first section title of a - file. The first section title is the "document title" (**doctitle**) of that - file and will appear in the menu. Every .rst file should have a title, each - title should have a link anchor. In :ref:`link-anchor` we describe - our recommended best way how to build a link anchor in the official - TYPO3 documentation. Here you see a title and a link anchor in - action: +Each reST document must have a title. It is overlined and underlined like this: .. code-block:: rst - .. _doc-title: + .. _rest-cheat-sheet: - ============== - Document Title - ============== + ============================= + Cheat sheet: reStructuredText + ============================= -2. Then use underlining only: +The anchor is used for permalinks. It should be lowercase with dashes between +words. During rendering special signs are converted into dashes and all letters changed to +lowercase if you ignore this. -.. code-block:: rst - - 1. ========== for the first level - 2. ---------- for the second level - 3. ~~~~~~~~~~ for the third level - 4. """""""""" for the fourth level +Use headers to divide your document into sections. Start with h2: -3. More levels will be rarely used. For sake of completeness here is the whole - hierarchy the automatic conversion tools uses. Stick to this order if more - levels are needed: +By convention we use the following underlines: .. code-block:: rst - 5. '''''''''' - 6. ^^^^^^^^^^ - 7. ########## - 8. ********** - 9. $$$$$$$$$$ - 10. `````````` - plus: +;.,_/%&! in that order - -Example -======= - -.. code-block:: rst + .. _h2-headline: + H2 Headline + =========== - .. _document-title: + .. _h3-headline: - ============== - Document Title - ============== + H3 Headline + ----------- - About this document ... + .. _h4-headline: - .. _topic-1: + H4 Headline + ~~~~~~~~~~~ - Topic 1 - ======= + .. _h5-headline: - Here we go. + H5 Headline + """"""""""" - .. _subtopic-1-1: + .. _h6-headline: - Subtopic 1.1 - ------------ + H6 Headline + ''''''''''' - Here we dive deeper + .. _another-h2-headline: + Another H2 Headline + =================== - .. _subsubtopic-1-1-1: +They look like this: - Subsubtopic 1.1.1 - ~~~~~~~~~~~~~~~~~ +.. _h2-headline: - And this is even more specific. +H2 Headline +=========== - .. _topic-2: +.. _h3-headline: - Topic 2 - ======= - ... +H3 Headline +----------- +.. _h4-headline: -Syntax -====== +H4 Headline +~~~~~~~~~~~ -Length of Underlines --------------------- +.. _h5-headline: -The length of the underlines **should** have the same length like the text. It -**should not** be longer or shorter. +H5 Headline +""""""""""" -Example 1: This Works -~~~~~~~~~~~~~~~~~~~~~ +.. _h6-headline: -.. code-block:: rst +H6 Headline +''''''''''' - .. _example-1: - - ========= - Example 1 - ========= - -Example 2: These headlines work but do not abide to the coding guidelines -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Here we see how we should not do it. The underlines are too long or too short. - -.. code-block:: rst +.. _syntax-headlines: - .. _example-2: +Syntax of headlines +=================== - ============== - Example 2 - ============== - - # Underline too long +The underlining special signs should be as long as the line but this is not +enforced. - .. _example-3: +Each headline should have an anchor. Otherwise permalinking does not work. - ======= - Example 3 - ======= - - # Underline too short +Keep anchors unless a concept is completely removed.