From 70860038425df9264c53e6e2da124a4f7a401a9e Mon Sep 17 00:00:00 2001 From: "lina.wolf" Date: Sat, 23 Nov 2024 08:10:14 +0100 Subject: [PATCH] [TASK] Tidy up basic chapters --- Documentation/Basics/About.rst | 36 -- Documentation/Basics/BasicPrinciples.rst | 355 ------------------ Documentation/Basics/HowToGetHelp.rst | 82 ---- Documentation/Basics/Index.rst | 66 +++- Documentation/Basics/Rendering.rst | 14 + Documentation/Howto/RenderingDocs/Index.rst | 1 - .../ContributeToSystemExtension.rst | 3 - Documentation/Index.rst | 9 +- 8 files changed, 77 insertions(+), 489 deletions(-) delete mode 100644 Documentation/Basics/About.rst delete mode 100644 Documentation/Basics/BasicPrinciples.rst delete mode 100644 Documentation/Basics/HowToGetHelp.rst create mode 100644 Documentation/Basics/Rendering.rst diff --git a/Documentation/Basics/About.rst b/Documentation/Basics/About.rst deleted file mode 100644 index 40d9570d..00000000 --- a/Documentation/Basics/About.rst +++ /dev/null @@ -1,36 +0,0 @@ -.. include:: /Includes.rst.txt -.. _about: - -================ -About this guide -================ - -This guide was written to help the reader to :ref:`contribute to the official TYPO3 -documentation ` and to :ref:`write documentation for their own -extensions `. - -Documentation written in :ref:`reStructured Text ` can be -:ref:`rendered ` using a TYPO3-specific theme and -automatically deployed to -https://docs.typo3.org by adding a :ref:`Webhook `. - -.. _credits: - -Credits -======= - -This document was originally written by Martin Bless. - -Special thanks to Xavier Perseguers, who wrote some of the original texts -in the retired TYPO3 Wiki and elsewhere. Some of the texts have been -incorporated into this document or at least served as a basis. - -Further chapters were added by Sybille Peters. - -A number of other people have helped by reviewing and refining the text -and pointing out missing information. For more contributors, see the -`list of contributors on GitHub for this manual -`__. - -We thank everyone for their help and hope that good documentation -about writing documentation will make it easier for others to contribute. diff --git a/Documentation/Basics/BasicPrinciples.rst b/Documentation/Basics/BasicPrinciples.rst deleted file mode 100644 index 348b0208..00000000 --- a/Documentation/Basics/BasicPrinciples.rst +++ /dev/null @@ -1,355 +0,0 @@ -.. include:: /Includes.rst.txt -.. _basic-principles: - -================ -Basic principles -================ - - -Introduction to TYPO3 documentation -=================================== - -For an excellent introduction, please see the 3 part series on Marcus -Schwemer's blog TYPO3 Worx: - -* `Guide to TYPO3 Documentation – Part 1: The User-Interface `__ -* `Guide to TYPO3 Documentation – Part 2: Content Structure `__ - -.. important:: - - Please note that the section "Contribution and ReST Helpers" in part 3 is - slightly outdated. Currently, using the Docker container for :ref:`rendering - ` is the recommended approach. If you edit on GitHub directly, - GitHub preview should be sufficient for making small changes. - -.. index:: TYPO3 documentation -.. _whats-typo3-documentation: - -What is the TYPO3 documentation? -================================ - -TYPO3 documentation may be one of the following: - -* It can be one of the `official manuals `__ - like :ref:`t3coreapi:start`. -* It can be the documentation of a - `system extension `__. -* It can be the documentation of a - `third party extension `__. -* TYPO3 documentation can also be a - `Changelog `__ - entry for the core, for example a documented breaking change or new feature. - - -.. _common-characteristics-typo3-docs: - -Common characteristics of TYPO3 documentation -============================================= - -All of these examples have a few things in common: - -* The documentation is rendered and found on https://docs.typo3.org -* The documentation has a **common theme**, all pages look similar and use the same styles -* Most of the documentation can be directly **edited by the community**. For third party - extensions, this depends on where and how the source-code is hosted and maintained. -* The source of the documentation is written (mostly) in reStructuredText (**reST**) -* All documentation is rendered using the **same rendering toolchain**. All documentation - can be rendered locally, with the officially supported Docker image. -* The documentation source files adhere to :ref:`file-structure` - (for example all documentation files in a - :file:`Documentation` subdirectory). -* Due to the conventions, the rendering of documentation can be automated and - every documentation project only requires a minimum of setup. - - -.. index:: TYPO3 documentation; Rendering -.. _whats-rendering: - -What is "rendering"? -==================== - -Rendering means (in this specific case) converting the reST -format (.rst files) into its final, readable form, which you can view in your -browser, like this page, which you are probably reading online. If not, load -https://docs.typo3.org/typo3cms/HowToDocument/BasicPrinciples.html in your browser. - -In comparison, this is what the original source file looks like: -https://docs.typo3.org/typo3cms/HowToDocument/_sources/BasicPrinciples.txt - -Technically, this means converting the reST (.rst files) into HTML, automatically -creating the menu, using the current theme to add additional styles and images. - - -.. index:: TYPO3 documentation; Types -.. _documentation-types: - -Documentation types -=================== - -.. hint:: - - See boilerplate texts for the start page on :ref:`index-rst`. - - -.. index:: TYPO3 documentation; Manual - -Manual ------- - -A "manual" in the context of TYPO3 documentation is being used to talk about -one unit of documentation, which usually has it's own git repository (or is -included in the git repository of an extension) and consists of one :file:`Documentation` -folder. A "manual" can be a tutorial, such as the :ref:`t3start:start`, a guide, -an extension manual or something else. - - -.. index:: TYPO3 documentation; Tutorial -.. _doc-type-tutorial: - -Tutorial --------- - -A tutorial is a manual. - -Tutorials are designed to be a **learning-oriented** resource that take -newcomers by the hand and guide them through a specific topic. To facilitate effective -learning, tutorials provide examples to illustrate the subjects they cover. - -They may not necessarily follow best-practices by the letter. They are -designed to make it easier to get started. - -The definitions for tutorials, guides, explanations and references were taken from -`Daniele Procida: What nobody tells you about documentation `__ - - -.. index:: TYPO3 documentation; How-to guide -.. _doc-type-guide: - -How-to guide ------------- - -A guide is a manual. - -Guides offer advice on **how best to achieve a given task**. They are goal oriented. - - -.. index:: TYPO3 documentation; Reference -.. _doc-type-reference: - -Reference ---------- - -A reference is well structured and allows the reader to find information about a specific -topic. They should be short and to the point. - - -.. index:: TYPO3 documentation; Extension manual -.. _doc-type-extension-manual: - -Extension manual ----------------- - -An extension manual covers only the extension. This documentation is (usually) included -in the source code of an extension in a :file:`Documentation` subdirectory. - - -.. index:: TYPO3 documentation; Official documentation -.. _doc-type-official: - -Official documentation ----------------------- - -This documentation is authored and maintained by the TYPO3 community. - -The Documentation Team generally maintains this documentation, but maintenance tasks -may be delegated to others, for example by giving write permission to GitHub repositories. - -In general, it is recommended for the TYPO3 experts to take on jobs of continuously updating -content and making sure it is correct and up to date. - - -.. index:: TYPO3 documentation; Community documentation -.. _doc-type-community: - -Community documentation ------------------------ - -Third party extension manuals are typically "community documentation". - -This documentation is usually maintained by the extension author. - -The TYPO3 Documentation Team cannot maintain "community documentation", but it -helps by providing documentation, support and an example extension manual. - - -.. index:: Contribution matrix -.. _overview-of-types: -.. _contribution-matrix: - -Documentation contribution matrix -================================= - - -Considering how to contribute, the things that differ for various kinds of documentation -are: - -* Where the issues are maintained (for example on Forge or GitHub) -* Where the source code (Git repository) is kept -* The workflow for making changes to the documentation - - -.. t3-field-list-table:: - :header-rows: 1 - - - :Type: Type of documentation - :Issues: Issues - :Source: Source Code (Git repository) - :Workflow: Workflow for making changes - - - :Type: Official `guides, tutorials `__, - `core docs `__, - etc. - :Issues: On page of rendered docs, click on :guilabel:`Issues` in the - footer on the bottom of the page - :Source: On page of rendered docs, click on :guilabel:`Repository` in - the footer, or click on :guilabel:`Edit on GitHub` on top right - :Workflow: Create GitHub pull request, see :ref:`docs-contribute`. - - - :Type: `TYPO3 Core Changelog `__ - :Issues: `Core issues on forge `__ - :Source: TYPO3 source code: `GitHub `__ - :Workflow: see :ref:`Contribution Guide: Add documentation ` - - - :Type: `System extensions `__ - :Issues: `Core issues on forge `__ - :Source: Same as for Changelog, inside TYPO3 source code: `GitHub `__, - :Workflow: see :ref:`Contribution Guide: Add documentation ` - - - :Type: `3rdparty extensions `__ - :Issues: On page of rendered docs, click on :guilabel:`Issues` link in footer - :Source: On page of rendered docs, click on :guilabel:`Repository` - link in footer, see :ref:`contribute-to-3rdparty-extension` - :Workflow: It depends, see :ref:`contribute-to-3rdparty-extension` - - - -.. index:: Official TYPO3 manuals - -Official TYPO3 manuals ----------------------- - -The official TYPO3 manuals are hosted on GitHub. Editing the documentation -requires a GitHub account and involves creating a pull request on GitHub. - -Find out more about how to contribute: :ref:`docs-contribute`. - - -.. index:: Core documentation - -Core documentation ------------------- - -The documentation for the TYPO3 Core (changelog and system extensions) is added -to the TYPO3 source code. For this reason, the workflow of changing -something in the core documentation is very similar to adding a patch -to the core. - -Find out more about the :ref:`core contribution workflow ` -in general or about :ref:`t3contribute:Adding-documentation` in the Contribution -Guide. - -In addition to using the core workflow, the core documentation can also -be changed via :ref:`"Edit on GitHub" `. -In this case, a Gerrit patch is created automatically from the pull request. - - -.. index:: Extension manual - -Extension manuals ------------------- - -The documentation for a 3rdparty extension is maintained within the -source-code of this extensions. If and where it is edited depends -on where the extension is hosted and maintained. - -If the extension is hosted on GitHub and correctly -:ref:`configured in Documentation/Settings.cfg `, -extension documentation contributors -can also make changes via :ref:`"Edit on GitHub" `. - -To find out how to contribute documentation for a specific extension: -:ref:`contribute-to-3rdparty-extension` - -.. index:: Extensions -.. _about-typo3-extensions: - -About TYPO3 extensions -====================== - -In TYPO3, basically everything is an extension. There are system extensions -and third party extensions: - - -.. index:: System extensions - -System extensions ------------------ - -System extensions (or core extensions) are extensions that are maintained -in the TYPO3 source. For a list of system extensions, look in the Extension -Manager or in the TYPO3 source, for example `GitHub: TYPO3.CMS: /typo3/sysext -`__. - -Examples for system extensions are: - -* `ext:form `__ -* `ext:fluid_styled_content `__ -* `ext:rte_ckeditor `__ - -Note, that if your system has been installed with Composer, not all system extensions may exist -in the system. - - -.. index:: pair: System extensions; Documentation - -System extension documentation -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Find the documentation for a system extension on -`System extensions `__. - -Not all system extensions have documentation at the moment. - -For more information about contributing to system extensions, see :ref:`contribute-to-system-extension` -in this guide. - -See also :ref:`overview-of-types` for an overview of the issues, source and workflow for various -kinds of documentation, including system extensions. - - -.. index:: Third-party extensions - -Third-party extensions ----------------------- - -Third party extensions are extension that can be created by anyone. They are not included in the TYPO3 core -codebase and are not officially supported by the TYPO3 core team. - -Often, but not necessarily, these extensions are hosted on GitHub. - -They can be installed by the TYPO3 Extension Manager or via Composer. - - -.. index:: pair: Third-party extensions; Documentation - -Third-party extension documentation -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Find the documentation on `Extensions by extension key `__. - -For more information about contributing to third party extension documentation or for your own extension, see -:ref:`contribute-to-3rdparty-extension`. See :ref:`how-to-start-docs-extension` for -information about starting extension documentation from scratch. - -See also :ref:`overview-of-types` for an overview of the issues, source and workflow for various -kinds of documentation, including third party extensions. diff --git a/Documentation/Basics/HowToGetHelp.rst b/Documentation/Basics/HowToGetHelp.rst deleted file mode 100644 index d397368c..00000000 --- a/Documentation/Basics/HowToGetHelp.rst +++ /dev/null @@ -1,82 +0,0 @@ -.. include:: /Includes.rst.txt -.. index:: - Help - Support -.. _how-to-get-help: -.. _slack: -.. _help: -.. _contact-us: - -============== -Help & Support -============== - -.. index:: - Help; Writing documentation - Slack; #typo3-documentation -.. _get-help-on-writing-docs: - -Get help on writing documentation -================================= - -If you wish to contribute to the docs, have questions about the -documentation or run into problems, the -`TYPO3 slack workspace `__ -is the place to be. - -In order -to join the slack workspace, you must `Register for TYPO3's Slack -Platform `__. On that page, -you will also find information about the most important channels. - -The channel **#typo3-documentation** is your channel of choice -for everything concerning TYPO3 documentation. - -If you have some general TYPO3 support issues, please use **#typo3-cms** -for that. - -If you are not sure which channel to use for your question you can -use **#random** where you get direct help or a hint for the right -channel. - -.. hint:: - Do not ask if you can ask a question. Ask your question directly. - - -.. index:: - Help; Using documentation - Slack; #typo3-documentation - -Get help on using documentation -=============================== - -The same method as in :ref:`get-help-on-writing-docs` applies: Post -your question in the **#typo3-documentation** channel. - -Don't worry, you will not be frowned upon if you don't know something. -Engagement and curiosity is a good thing! You may even have stumbled -upon something that is not documented well or is not user friendly. -In that case, let us know about it! - - -.. index:: pair: Contact; Documentation Team - -Contact the Documentation Team -============================== - -If you wish to contact the Documentation Team, you can also use the -**#typo3-documentation** channel on Slack. - -Additionally, you can contact us via `email `__. - - -.. index:: - Help; Support for TYPO3 - Slack; #typo3-cms - -General support for TYPO3 -========================= - -Go to https://typo3.org/help/. There, you will also be directed to the -Slack channel **#typo3-cms**, but some other methods for getting help -and support are listed as well. diff --git a/Documentation/Basics/Index.rst b/Documentation/Basics/Index.rst index 18c04cbe..d48cb6f1 100644 --- a/Documentation/Basics/Index.rst +++ b/Documentation/Basics/Index.rst @@ -1,10 +1,62 @@ -:orphan: +:navigation-title: Getting started +.. include:: /Includes.rst.txt +.. _basics: -====== -Basics -====== +======================================== +Getting started with TYPO3 Documentation +======================================== -.. menu:: - :glob: +.. contents:: Content on this page - * +.. _common-characteristics-typo3-docs: + +Common characteristics of TYPO3 documentation +============================================= + +All of these examples have a few things in common: + +* The documentation is rendered and found on https://docs.typo3.org +* The documentation has a **common theme**, all pages look similar and use the same styles +* Most of the documentation can be directly **edited by the community**. For third party + extensions, this depends on where and how the source-code is hosted and maintained. +* The source of the documentation is written (mostly) in reStructuredText (**reST**) +* All documentation is rendered using the **same rendering toolchain**. All documentation + can be rendered locally, with the officially supported Docker image. +* The documentation source files adhere to :ref:`file-structure` + (for example all documentation files in a + :file:`Documentation` subdirectory). +* Due to the conventions, the rendering of documentation can be automated and + every documentation project only requires a minimum of setup. + +.. _slack: +.. _contact-us: +.. _get-help-on-writing-docs: + +Get help on writing documentation +================================= + +If you wish to contribute to the docs, have questions about the +documentation or run into problems, the +`TYPO3 slack workspace `__ +is the place to be. + +In order +to join the slack workspace, you must `Register for TYPO3's Slack +Platform `__. On that page, +you will also find information about the most important channels. + +The channel **#typo3-documentation** is your channel of choice +for everything concerning TYPO3 documentation. + +If you have some general TYPO3 support issues, please use **#typo3-cms** +for that. + +.. _how-to-get-help: +.. _help: + +General support for TYPO3 +========================= + +Go to https://typo3.org/help/. There, you will also be directed to the +Slack channel **#typo3-cms**, but some other methods for getting help +and support are listed as well. diff --git a/Documentation/Basics/Rendering.rst b/Documentation/Basics/Rendering.rst new file mode 100644 index 00000000..00d24a18 --- /dev/null +++ b/Documentation/Basics/Rendering.rst @@ -0,0 +1,14 @@ +.. include:: /Includes.rst.txt + +.. _rendering-docs-quickstart: + +================= +Rendering locally +================= + +For local rendering you can use the following command in the directory that +contains the :path:`Documentation` folder: + +.. include:: /_Includes/_LocalRendering.rst.txt + +For more options see :ref:`render-documentation-with-docker`. diff --git a/Documentation/Howto/RenderingDocs/Index.rst b/Documentation/Howto/RenderingDocs/Index.rst index f84a8b13..aa35c754 100644 --- a/Documentation/Howto/RenderingDocs/Index.rst +++ b/Documentation/Howto/RenderingDocs/Index.rst @@ -7,7 +7,6 @@ Rendering; Docker Rendering; Commands .. _rendering-docs: -.. _rendering-docs-quickstart: .. _render-documenation-with-docker: .. _render-documentation-with-docker: diff --git a/Documentation/Howto/WritingDocForExtension/ContributeToSystemExtension.rst b/Documentation/Howto/WritingDocForExtension/ContributeToSystemExtension.rst index 8af1c4d5..a5ca9866 100644 --- a/Documentation/Howto/WritingDocForExtension/ContributeToSystemExtension.rst +++ b/Documentation/Howto/WritingDocForExtension/ContributeToSystemExtension.rst @@ -9,9 +9,6 @@ Contribute to system extensions The documentation for system extensions is maintained inside the TYPO3 source code, so the contribution workflow is a little different. -For more information about the various contribution workflows, -see :ref:`overview-of-types`. - * When it comes to documentation that is contained within the core (like system extension documentation and changelog), you would use Forge to report **issues**, using the category "Documentation": diff --git a/Documentation/Index.rst b/Documentation/Index.rst index 38124b81..f957bcdf 100644 --- a/Documentation/Index.rst +++ b/Documentation/Index.rst @@ -91,11 +91,9 @@ reStructuredText (reST). :hidden: :caption: BASICS - Basics/About - Basics/HowToGetHelp - Basics/BasicPrinciples + Basics/Index Basics/RstCheatSheet - + Basics/Rendering .. toctree:: :hidden: @@ -109,7 +107,8 @@ reStructuredText (reST). :hidden: :caption: HOWTOS - Howto/* + Howto/EditOnGithub + Howto/EditLocal Howto/*/Index .. toctree::