:orphan: .. include:: Includes.txt .. _Tip-of-the-day-outdated: ============= Outdated tips ============= .. important:: Do not follow these tips! They are outdated. .. _tip-of-the-day-trigger-rebuild-old: .. rst-class:: panel panel-default Outdated: Trigger Documentation Rendering on the Documentation Server ===================================================================== .. important:: Since moving to the new documentation server, this tip is outdated. Usually, extension documentation should be rerendered automatically. If you made a change that has been merged, but it is not yet visible, do the following: #. Wait up to 10 minutes #. Reload your browser You may also render the repository locally, to make sure there are no build errors breaking the rendering. See :ref:`render-troubleshooting-errors`. You can also look in the files in :file:`_buildinfo` online to see the exitcodes and warnings. For example, for this manual: https://docs.typo3.org/typo3cms/HowToDocument/stable/_buildinfo/ If this yields no results, you can iniate a rebuild: To trigger a rebuild of a manual, click the "request_rebuild.php" file in the respective .../\*.git.make folder. Here are the links: - Request rebuild for `the official TYPO3 CMS manuals `_ - Request rebuild for `TYPO3 system extension manuals `_ - Request rebuild for `manuals of extensions hosted on GitHub `_ .. _tip-of-the-day-2017-02-13: .. rst-class:: panel panel-default Outdated: 'toctree' and the Hierarchical Structure of a Manual ============================================================== **Update:** Part of this description has been migrated to :ref:`rest-menu-hierachy`. (2019-01-06). 2017-02-13 by Martin Bless TYPO3 documentation usually starts with a textfile :file:`PROJECT/Documentation/Index.rst`. The text may go into more than one textfile and these can be "pulled in" and referenced by the `.. toctree:: `__ directive. Note: #. Each `.. toctree::` directive creates a *sublevel* of headlines in the menu. #. The sublevel refers to the *current level*. Problem Sometimes you don't get what you expect: .. code-block:: rst ================ My Documentation ================ Introduction ============ This project does something very useful ... See the individual chapters. .. toctree:: Chapter-1 Chapter-2 Chapter-3 The example feels very natural. We are thinking of the introduction followed by the single chapters. Unfortunately we get something different. The chapters will all be a *subpart* of *Introduction* and not at the same level. It is exactly what the Sphinx documentation states and there is no easy way to "tweak" this behavior. Solution Use these rules of thumb: #. All or nothing: Pull in *all* content of a given level via `toctree` or don't use `toctree` at all. #. Or, in other words: Do not use a headline ("section") in a document before a `.. toctree::` directive unless you really want to place the pulled in documents at a *sublevel of that section*. Here is how we can fix the example: Move the introduction to an extra file and pull it in just like the others. **Fixed example:** .. code-block:: rst ================ My Documentation ================ You can have text here. But don't introduce headlines, if you want to have the pulled in files at the same level. .. toctree:: Introduction Chapter-1 Chapter-2 Chapter-3 Now the *document titles* (not shown here) of the files :file:`Introduction.rst`, :file:`Chapter-1.rst`, :file:`Chapter-2` and :file:`Chapter-3` will all be at the sublevel of `My Documentation` in the menu. .. _tip-of-the-day-2016-10-08: .. rst-class:: panel panel-default OUtdated: How to Write Inline Code ================================== **Update:** This information has been migrated to :ref:`Inline-Code` and extended (2019-01-06). 2016-10-08 by Martin Bless Preferred: Use Single Backticks ` ... ` --------------------------------------- 1. In general we are using `interpreted text roles`_ for small inline code snippets. Surround the code by *single backticks* and don't start or end the code with whitespace. Example: Type ```2 + 2 = 4``` to get `2 + 2 = 4` as result. 2. Just write the code as it is - don't escape or double anything. 3. Even better: Explicitly specify what kind of code (= textrole) it is. This better shows the semantics and in the output there may be a a special coloring or highlighting (on the way): ================ ================================================= ============================================ === Role Source Output Note ================ ================================================= ============================================ === (default) ```result = (1 + x) * 32``` `result = (1 + x) * 32` This works because in :file:`Includes.txt` we set the default role to ``:code:`...``` aspect ``:aspect:`Description:``` :aspect:`Description:` For better optics code ``:code:`result = (1 + x) * 32``` :code:`result = (1 + x) * 32` file ``:file:`/etc/passwd``` :file:`/etc/passwd` js ``:js:`var f = function () {return 1;}``` :js:`var f = function () {return 1;}` html ``:html:```` :html:`` ts ``:ts:`lib.hello.value = Hello World!``` :ts:`lib.hello.value = Hello World!` typoscript ``:typoscript:`lib.hello.value = Hello World!``` :typoscript:`lib.hello.value = Hello World!` php ``:php:`$result = $a + 23;``` :php:`$result = $a + 23;` ================ ================================================= ============================================ === When to Use Literal Code \`\`...`` ---------------------------------- Things get tricky if your inline code already contains single backquotes (backticks). 4. In many cases you can still use the *interpreted textrole* as described in 1. to 3. For example we can write ``:code:`:html:`
```` to get :code:`:html:`
`` This is possible if (a) your code doesn't start with a backtick and (b) if no backtick in your code has a trailing whitespace. 5. **But:** To be really free to include inline any code containing backticks you will want to use `inline literals`_. Again: Don't escape or double anything, whitespace is maintained. *Example:* Write .. code-block:: rst SQL-example code: ``SELECT `tt_content` . `bodytext` AS `t1` . `text`;`` to get: SQL-example code: ``SELECT `tt_content` . `bodytext` AS `t1` . `text`;`` **The drawbacks** of literal inline code notation are: - there is no way to semantically classify the kind of code - there is no special coloring or highlighting - the raw reST code looks less beautiful and is less readable .. _interpreted text roles: http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#interpreted-text .. _inline literals: http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#inline-literals .. _tip-of-the-day-2016-09-11: .. rst-class:: panel panel-default Outdated: Add borders to Your Images ==================================== **Update:** It is now also possible to add a drop shadow (`:class: with-shadow`) to images. This is recommended. For an up-to-date description of how to embed images, see :ref:`how-to-document-images` (2019-01-06). 2016-09-11 by Martin Bless The next version of the `t3SphinxThemeRtd`_ (following 3.6.0) will know a general css class `with-border`. Some images look best without an extra border because their outline is clearly visible. Others benefit from having a border because they are not separated enough from the background. Example: .. _t3SphinxThemeRtd: https://github.com/TYPO3-Documentation/t3SphinxThemeRtd 1. Here is the markup to include an image as a 'figure'. Figures always are of css type 'block' and can have a caption:: .. figure:: images/2016-09-11-2.png 2. And this is what we see. The image is not clearly distinguished: .. figure:: images/2016-09-11-2.png 3. Now the same markup plus the extra class:: .. figure:: images/2016-09-11-2.png :class: with-shadow .. figure:: images/2016-09-11-2.png :class: with-shadow