Merge pull request #41 from alexander-nitsche/task-update-docs

[TASK] Align with new TYPO3 documentation standards

.editorconfig

@@ -26,10 +26,14 @@ indent_size = 2
 indent_style = tab
 
 # ReST-Files
-[*.rst]
+[*.{rst,rst.txt}]
 indent_size = 3
 max_line_length = 80
 
+# Markdown-Files
+[*.md]
+max_line_length = 80
+
 # YAML-Files
 [*.{yaml,yml}]
 indent_size = 2

Documentation/Includes.rst.txt

@@ -0,0 +1,34 @@
+.. More information about this file:
+   https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/GeneralConventions/FileStructure.html#includes-rst-txt
+
+.. ----------
+.. text roles
+.. ----------
+
+.. role:: aspect(emphasis)
+.. role:: bash(code)
+.. role:: html(code)
+.. role:: js(code)
+.. role:: php(code)
+.. role:: rst(code)
+.. role:: sep(strong)
+.. role:: sql(code)
+
+.. role:: tsconfig(code)
+   :class: typoscript
+
+.. role:: typoscript(code)
+.. role:: xml(code)
+   :class: html
+
+.. role:: yaml(code)
+
+.. default-role:: code
+
+.. ---------
+.. highlight
+.. ---------
+
+.. By default, code blocks use PHP syntax highlighting
+
+.. highlight:: php

Documentation/Index.rst

@@ -1,61 +1,61 @@
-.. every .rst file should include Includes.txt
-.. use correct path!
+.. include:: /Includes.rst.txt
 
-.. include:: Includes.txt
+============================
+Dashboard Widgets Collection
+============================
 
+:Extension key:
+   widgets
 
-.. Every manual should have a start label for cross-referencing to
-.. start page. Do not remove this!
-
-.. _start:
-
-=============================================================
-Widgets
-=============================================================
+:Package name:
+   friendsoftypo3/widgets
 
 :Version:
    |release|
 
 :Language:
    en
 
-:Authors:
-   Richard Haeser, Koen Wouters
+:Author:
+   Richard Haeser, Koen Wouters & Contributors
 
 :License:
-   This extension documentation is published under the
-   `CC BY-NC-SA 4.0 <https://creativecommons.org/licenses/by-nc-sa/4.0/>`__ (Creative Commons)
-   license
+   This document is published under the
+   `Creative Commons BY-NC-SA 4.0 <https://creativecommons.org/licenses/by-nc-sa/4.0/>`__
+   license.
 
-A collection of Widgets for the Dashboard of TYPO3.
+:Rendered:
+   |today|
 
-**TYPO3**
+----
 
-   The content of this document is related to TYPO3 CMS,
-   a GNU/GPL CMS/Framework available from `typo3.org
-   <https://typo3.org/>`_ .
+This extension contains various widgets that can be used on the TYPO3 backend
+:doc:`dashboard <ext_dashboard:Index>`.
 
-**Community Documentation:**
+It currently contains the following widgets:
 
-   This documentation is community documentation for the TYPO3 extension widgets
+*  **Current Online Users**: Shows which users are currently online.
+*  **Status Report**: Gives you an overview of errors and warnings in your
+   installation.
+*  **Pages without meta description**: Provides a list of recently edited pages
+   that lack a meta description.
 
-   It is maintained as part of this third party extension.
+----
 
-   If you find an error or something is missing, please:
-   `Report a Problem <https://github.com/FriendsOfTYPO3/widgets/issues/new>`__
+**Table of Contents:**
 
-**For Contributors**
+.. toctree::
+   :maxdepth: 2
+   :titlesonly:
 
-   You are welcome to help improve this guide. Just click on "Edit me on GitHub"
-   on the top right to submit your change request.
+   Introduction/Index
+   Installation/Index
+   Widgets/Index
 
+.. Meta Menu
 
 .. toctree::
-   :maxdepth: 3
    :hidden:
 
-
-   Introduction/Index
-   Widgets/Index
-   Installation/Index
-
+   Sitemap
+   genindex

Documentation/Installation/Index.rst

@@ -1,4 +1,4 @@
-.. include:: ../Includes.txt
+.. include:: /Includes.rst.txt
 .. highlight:: bash
 
 .. _installation:

Documentation/Introduction/Index.rst

@@ -1,4 +1,4 @@
-.. include:: ../Includes.txt
+.. include:: /Includes.rst.txt
 
 
 .. _introduction:
@@ -12,18 +12,17 @@ Introduction
 What does it do?
 ================
 
-This extension will provide several widgets to use in the Dashboard for TYPO3. Check
-the :ref:`widgets` page for an overview of all available widgets.
+This extension will provide several widgets to use in the Dashboard for TYPO3.
+Check the :ref:`widgets` page for an overview of all available widgets.
 
 .. _screenshots:
 
 Screenshots
 ===========
 
-.. figure:: ../Images/Screenshot1.png
+.. figure:: /Images/Dashboard.png
    :class: with-shadow
    :alt: Some widgets
-   :width: 500px
-
-   An overview of some of the widgets in this extension
+   :width: 820px
 
+   Some widgets from the collection on the TYPO3 dashboard

Documentation/Settings.cfg

@@ -1,17 +1,62 @@
+# More information about this file:
+# https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/GeneralConventions/FileStructure.html#settings-cfg
+
 [general]
-project     = Widgets
-release     = latest
-copyright   = by Friends of TYPO3
+
+project     = Dashboard Widgets Collection
+version     = main (development)
+release     = main (development)
+copyright   = since 2020 by the TYPO3 contributors
 
 [html_theme_options]
-github_branch        = master
+
+# "Edit on GitHub" button
 github_repository    = FriendsOfTYPO3/widgets
+github_branch        = master
 
-project_contact      =
-project_home         = https://github.com/FriendsOfTYPO3/widgets
-project_issues       = https://github.com/FriendsOfTYPO3/widgets/issues
+# Footer links
+project_home         = https://extensions.typo3.org/extension/widgets
+project_contact      = https://typo3.slack.com/archives/C025BQLFA
 project_repository   = https://github.com/FriendsOfTYPO3/widgets
+project_issues       = https://github.com/FriendsOfTYPO3/widgets/issues
+project_discussions  =
+
+use_opensearch       =
 
 [intersphinx_mapping]
-dashboard       = https://docs.typo3.org/c/typo3/cms-dashboard/master/en-us/
 
+# Official TYPO3 manuals
+# h2document     = https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/
+# t3cheatsheets  = https://docs.typo3.org/m/typo3/docs-cheatsheets/main/en-us/
+# t3contribute   = https://docs.typo3.org/m/typo3/guide-contributionworkflow/main/en-us/
+# t3coreapi      = https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/
+# t3docteam      = https://docs.typo3.org/m/typo3/team-t3docteam/main/en-us/
+# t3editors      = https://docs.typo3.org/m/typo3/tutorial-editors/main/en-us/
+# t3extbasebook  = https://docs.typo3.org/m/typo3/book-extbasefluid/main/en-us/
+# t3extexample   = https://docs.typo3.org/m/typo3/guide-example-extension-manual/main/en-us/
+# t3home         = https://docs.typo3.org/
+# t3install      = https://docs.typo3.org/m/typo3/guide-installation/main/en-us/
+# t3l10n         = https://docs.typo3.org/m/typo3/guide-frontendlocalization/main/en-us/
+# t3sitepackage  = https://docs.typo3.org/m/typo3/tutorial-sitepackage/main/en-us/
+# t3start        = https://docs.typo3.org/m/typo3/tutorial-getting-started/main/en-us/
+# t3tca          = https://docs.typo3.org/m/typo3/reference-tca/main/en-us/
+# t3templating   = https://docs.typo3.org/m/typo3/tutorial-templating/main/en-us/
+# t3translate    = https://docs.typo3.org/m/typo3/guide-frontendlocalization/main/en-us/
+# t3tsconfig     = https://docs.typo3.org/m/typo3/reference-tsconfig/main/en-us/
+# t3tsref        = https://docs.typo3.org/m/typo3/reference-typoscript/main/en-us/
+# t3ts45         = https://docs.typo3.org/m/typo3/tutorial-typoscript-in-45-minutes/main/en-us/
+# t3viewhelper   = https://docs.typo3.org/other/typo3/view-helper-reference/main/en-us/
+# t3upgrade      = https://docs.typo3.org/m/typo3/guide-installation/main/en-us/
+
+# TYPO3 system extensions
+# ext_adminpanel     = https://docs.typo3.org/c/typo3/cms-adminpanel/main/en-us/
+# ext_core           = https://docs.typo3.org/c/typo3/cms-core/main/en-us/
+ext_dashboard      = https://docs.typo3.org/c/typo3/cms-dashboard/10.4/en-us/
+# ext_felogin        = https://docs.typo3.org/c/typo3/cms-felogin/main/en-us/
+# ext_form           = https://docs.typo3.org/c/typo3/cms-form/main/en-us/
+# ext_fsc            = https://docs.typo3.org/c/typo3/cms-fluid-styled-content/main/en-us/
+# ext_indexed_search = https://docs.typo3.org/c/typo3/cms-indexed-search/main/en-us/
+# ext_rte_ckeditor   = https://docs.typo3.org/c/typo3/cms-rte-ckeditor/main/en-us/
+# ext_scheduler      = https://docs.typo3.org/c/typo3/cms-scheduler/main/en-us/
+# ext_seo            = https://docs.typo3.org/c/typo3/cms-seo/main/en-us/
+# ext_workspaces     = https://docs.typo3.org/c/typo3/cms-workspaces/main/en-us/

Documentation/Sitemap.rst

@@ -0,0 +1,9 @@
+:template: sitemap.html
+
+.. include:: /Includes.rst.txt
+
+=======
+Sitemap
+=======
+
+.. The sitemap.html template will insert here the page tree automatically.

Documentation/Widgets/Index.rst

@@ -1,4 +1,4 @@
-.. include:: ../Includes.txt
+.. include:: /Includes.rst.txt
 
 
 .. _widgets:

Documentation/Widgets/OnlineUsersWidget.rst

@@ -1,4 +1,4 @@
-.. include:: ../Includes.txt
+.. include:: /Includes.rst.txt
 
 .. _online-users-widget:
 
@@ -10,10 +10,9 @@ This widget will show you who is currently logged in in the backend of your
 TYPO3 installation. This can be quite useful when you want to do maintenance
 and need to know if people are still using the installation.
 
-.. figure:: ../Images/OnlineUsersWidget.png
+.. figure:: /Images/OnlineUsersWidget.png
    :class: with-shadow
    :alt: Show the current online users
-   :width: 500px
 
    An overview of the current online users
 

Documentation/Widgets/PagesWithoutDescriptionWidget.rst

@@ -1,4 +1,4 @@
-.. include:: ../Includes.txt
+.. include:: /Includes.rst.txt
 
 .. _pages-without-description-widget:
 
@@ -14,35 +14,38 @@ This widget will show you the last edited pages without a meta description
 specified. You can click on the pencil icon behind every page to directly edit
 the page properties of the specific page.
 
-.. figure:: ../Images/PagesWithoutDescriptionWidget.png
+.. figure:: /Images/PagesWithoutDescriptionWidget.png
    :class: with-shadow
    :alt: This widget is showing the last edited pages without a meta description
-   :width: 500px
 
    This widget is showing the last edited pages without a meta description
 
 .. important::
 
-   This widget is only available when you have **EXT:seo** installed and activated
-
+   This widget is only available when you have
+   `EXT:seo <https://extensions.typo3.org/extension/seo>`__
+   installed and activated.
 
 Options
 -------
-This widget has some options. To override the default options, see :ref:`Adjust settings of registered widgets <dashboard:adjust-settings-of-registered-widgets>`.
 
+This widget has some options. To override the default options, see
+":ref:`ext_dashboard:adjust-settings-of-widget`" in the dashboard documentation.
+
+.. confval:: excludedDoktypes
 
-.. option:: $excludedDoktypes
+   :type: string
+   :default: ``3, 4, 6, 7, 199, 254, 255``
 
    Some doktypes are not real pages and can be excluded from this overview.
 
-   **Default:** 3, 4, 6, 7, 199, 254, 255
+.. confval:: limit
 
-.. option:: $limit
+   :type: int
+   :default: ``8``
 
    The number of pages without a meta description to show within the widget.
 
-   **Default:** 8
-
 An example:
 
 :file:`Configuration/Services.yaml`::