docs: Moved Scripting from /reference to /manual

Also made the Python Scripts page less prominent by moving it into the Export Formats category and added additional warnings and small adjustments to guide people to using JavaScript instead.
mapeditor · Mar 8, 2024 · d983dff · d983dff
1 parent 21d8ceb
commit d983dff
Show file tree

Hide file tree

Showing 39 changed files with 78 additions and 65 deletions.
diff --git a/docs/conf.py b/docs/conf.py
@@ -36,6 +36,7 @@
     'myst_parser',
     'sphinx_design',
     'sphinx_rtd_theme',
+    'sphinx_reredirects',
 ]
 
 myst_enable_extensions = [
@@ -136,6 +137,10 @@
     ]
 }
 
+redirects = {
+    "reference/scripting": "../../manual/scripting/",
+}
+
 
 # -- Options for HTMLHelp output ------------------------------------------
 

diff --git a/docs/index.rst b/docs/index.rst
@@ -27,7 +27,7 @@ Tiled Documentation
    manual/export
    manual/keyboard-shortcuts
    manual/preferences
-   manual/python
+   manual/scripting
 
 .. toctree::
    :maxdepth: 2
@@ -38,4 +38,3 @@ Tiled Documentation
    reference/tmx-changelog
    reference/json-map-format
    reference/global-tile-ids
-   reference/scripting
diff --git a/docs/manual/export-custom.rst b/docs/manual/export-custom.rst
@@ -11,16 +11,24 @@ file formats.
 Using JavaScript
 ~~~~~~~~~~~~~~~~
 
-Tiled is :doc:`extendable using JavaScript </reference/scripting>` and it is
+Tiled is :doc:`extendable using JavaScript </manual/scripting>` and it is
 possible to add custom export formats using `tiled.registerMapFormat
-<https://www.mapeditor.org/docs/scripting/modules/tiled.html#registermapformat>`__ or `tiled.registerTilesetFormat
-<https://www.mapeditor.org/docs/scripting/modules/tiled.html#registertilesetformat>`__.
+<https://www.mapeditor.org/docs/scripting/modules/tiled.html#registerMapFormat>`__ or `tiled.registerTilesetFormat
+<https://www.mapeditor.org/docs/scripting/modules/tiled.html#registerTilesetFormat>`__.
+
+This is the recommended way to add support for custom map or tileset formats.
 
 Using Python
 ~~~~~~~~~~~~
 
-It is also possible to write :doc:`Python scripts <python>` to add
-support for importing or exporting custom map formats.
+On some platforms, it is also possible to write :doc:`Python scripts <python>`
+to add support for importing or exporting custom map and tileset formats.
+
+.. warning::
+
+    Python scripting is not supported by the macOS release nor the Tiled snap
+    release for Ubuntu. The plugin is also very specific in the supported
+    Python version. Hence, its use is not recommend.
 
 Using C++
 ~~~~~~~~~

diff --git a/docs/manual/export.rst b/docs/manual/export.rst
@@ -27,6 +27,7 @@ or tileset itself).
    export-tbin
    export-other
    export-custom
+   python
    export-image
 
 .. note::

diff --git a/docs/manual/introduction.rst b/docs/manual/introduction.rst
@@ -33,7 +33,7 @@ rotated. Object layers offer a lot of flexibility to add almost any
 information to your level that your game needs.
 
 Other things worth mentioning are the support for adding custom map or tileset
-formats through plugins, :doc:`extending Tiled </reference/scripting>` with
+formats through plugins, :doc:`extending Tiled </manual/scripting>` with
 JavaScript, the tile stamp memory, :ref:`tile animation support
 <tile-animation-editor>` and the :ref:`tile collision editor
 <tile-collision-editor>`.

diff --git a/docs/manual/preferences.rst b/docs/manual/preferences.rst
@@ -218,7 +218,7 @@ Plugins
 -------
 
 Here you can choose which plugins are enabled, as well as opening the
-:doc:`scripted extensions </reference/scripting>` folder.
+:doc:`scripted extensions </manual/scripting>` folder.
 
 Plugins add support for map and/or tileset file formats. Some generic plugins
 are enabled by default, while more specific ones need to be manually enabled.

diff --git a/docs/manual/projects.rst b/docs/manual/projects.rst
@@ -24,7 +24,7 @@ Compatibility Version
 
 Extensions Directory
    A project-specific directory where you can put :doc:`Tiled extensions
-   </reference/scripting>`. It defaults to simply ``extensions``, so when you
+   </manual/scripting>`. It defaults to simply ``extensions``, so when you
    have a directory called "extensions" alongside your project file it will be
    picked up automatically.
 
@@ -71,7 +71,7 @@ just type the name of the file you'd like to open.
    There are many ways in which the projects could be made more powerful:
 
    -  Make the project accessible through the :doc:`scripting API
-      </reference/scripting>`.
+      </manual/scripting>`.
 
    -  Allow turning off features on a per-project basis, to simplify the UI
       and reduce the chance of accidentally doing something your project

diff --git a/docs/manual/python.rst b/docs/manual/python.rst
@@ -4,15 +4,13 @@ Python Scripts
 .. note::
 
     Since Tiled 1.3, Tiled can be :doc:`extended using JavaScript
-    </reference/scripting>`. The JavaScript API provides a lot more
+    </manual/scripting>`. The JavaScript API provides a lot more
     opportunity for extending Tiled's functionality than just adding custom
     map formats. It is fully documented and works out of the box on all
-    platforms. It should be preferred over the Python plugin when possible.
+    platforms. It recommended over the Python plugin whenever possible.
 
-Tiled ships with a plugin that enables you to use Python 3 to add
-support for custom map formats. This is nice especially since you don't
-need to compile Tiled yourself and the scripts are easy to deploy to any
-platform.
+Tiled ships with a plugin that enables you to use Python 3 to add support for
+custom map and tileset formats.
 
 For the scripts to get loaded, they should be placed in ``~/.tiled``.
 Tiled watches this directory for changes, so there is no need to restart
@@ -50,7 +48,8 @@ There are several `example scripts`_ available in the repository.
     However, currently Linux builds are done on Ubuntu 20.04 against
     Python 3.8, and you'd need to install the same version somehow.
 
-    The Python plugin is currently not available for macOS releases.
+    The Python plugin is not available for macOS releases, nor in the Ubuntu
+    snap.
 
 Example Export Plugin
 ---------------------

diff --git a/docs/reference/scripting.rst → docs/manual/scripting.rst b/docs/reference/scripting.rst → docs/manual/scripting.rst
@@ -66,9 +66,9 @@ directory of the ``.tiled-project`` file, but this can be changed in the
 .. warning::
 
     Since Tiled 1.7, project-specific extensions are only enabled by default
-    for projects you created. When opening any other project, a popup will
-    notify you when the project has a scripted extensions directory, allowing
-    you to enable extensions for that project.
+    for new projects you save from Tiled. When opening any other project, a
+    popup will notify you when the project has a scripted extensions directory,
+    allowing you to enable extensions for that project.
 
     Always be careful when enabling extensions on projects you haven't
     created, since extensions have access to your files and can execute

diff --git a/docs/reference/support-for-tmx-maps.rst b/docs/reference/support-for-tmx-maps.rst
@@ -278,7 +278,7 @@ Godot
 - Tiled ships with a plugin for exporting to :ref:`Godot 4 <godot4-export>` as .tscn scene files.
 - `Tiled Map Importer <https://godotengine.org/asset-library/asset/25>`__ imports each map as Godot scene which can be instanced or inherited (`forum announcement <http://discourse.mapeditor.org/t/importer-plugin-for-godot-engine/1833/1>`__).
 - `Godot Tiled importer (Mono version) <https://github.com/mi-sts/godot_tiled_importer>`__ imports Tiled maps exported to JSON (.tmj) format. Supports all map orientations.
-- `Tiled To Godot Export <https://github.com/MikeMnD/tiled-to-godot-export>`__ is a Tiled :doc:`JavaScript extension </reference/scripting>` for exporting Tilemaps and Tilesets in Godot 3.2 format (`forum announcement <https://discourse.mapeditor.org/t/tiled-editor-map-and-tileset-integration-with-godot-3-2/4347>`__).
+- `Tiled To Godot Export <https://github.com/MikeMnD/tiled-to-godot-export>`__ is a Tiled :doc:`JavaScript extension </manual/scripting>` for exporting Tilemaps and Tilesets in Godot 3.2 format (`forum announcement <https://discourse.mapeditor.org/t/tiled-editor-map-and-tileset-integration-with-godot-3-2/4347>`__).
 
 Grid Engine
 ~~~~~~~~~~~

diff --git a/docs/reference/tmx-map-format.rst b/docs/reference/tmx-map-format.rst
@@ -243,7 +243,7 @@ rendered.
 -  **height:** The image height in pixels (optional)
 
 Tiled maps or tilesets with embedded image data can currently only be created
-using the :doc:`JavaScript API </reference/scripting>`, or in custom tools
+using the :doc:`JavaScript API </manual/scripting>`, or in custom tools
 based on ``libtiled`` (Qt/C++) or `tmxlib
 <https://pypi.python.org/pypi/tmxlib>`__ (Python).
 

diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -1,5 +1,6 @@
 Sphinx >= 6, < 7
 docutils >= 0.18.1
 myst-parser >= 1.0
+sphinx-reredirects >= 0.1
 sphinx-rtd-theme >= 1.2
 sphinx_design >= 0.3
diff --git a/docs/scripting-doc/index.d.ts b/docs/scripting-doc/index.d.ts
@@ -5,7 +5,7 @@
  * {@link tiled.registerAction | custom actions} and {@link tiled.registerTool | new tools}.
  * Scripts can also {@link Signal | automate actions based on signals}.
  *
- * See the [Tiled Manual](https://doc.mapeditor.org/en/stable/reference/scripting) for more information on writing or installing extensions.
+ * See the [Tiled Manual](https://doc.mapeditor.org/en/stable/manual/scripting) for more information on writing or installing extensions.
  *
  * ### Type Definitions
  *

diff --git a/src/tiled/mainwindow.cpp b/src/tiled/mainwindow.cpp
@@ -1598,7 +1598,7 @@ void MainWindow::openProjectExtensionsPopup()
 
     auto label = new QLabel;
     label->setTextFormat(Qt::RichText);
-    label->setText(tr("The current project contains <a href=\"https://doc.mapeditor.org/en/stable/reference/scripting/\">scripted extensions</a>.<br><i>Make sure you trust those extensions before enabling them!</i>"));
+    label->setText(tr("The current project contains <a href=\"https://doc.mapeditor.org/en/stable/manual/scripting/\">scripted extensions</a>.<br><i>Make sure you trust those extensions before enabling them!</i>"));
     label->setOpenExternalLinks(true);
 
     auto enableButton = new QPushButton(tr("&Enable Extensions"));

diff --git a/translations/tiled_ar_DZ.ts b/translations/tiled_ar_DZ.ts
@@ -4483,7 +4483,7 @@ Please select specific format.</source>
     </message>
     <message>
         <location line="+35"/>
-        <source>The current project contains &lt;a href=&quot;https://doc.mapeditor.org/en/stable/reference/scripting/&quot;&gt;scripted extensions&lt;/a&gt;.&lt;br&gt;&lt;i&gt;Make sure you trust those extensions before enabling them!&lt;/i&gt;</source>
+        <source>The current project contains &lt;a href=&quot;https://doc.mapeditor.org/en/stable/manual/scripting/&quot;&gt;scripted extensions&lt;/a&gt;.&lt;br&gt;&lt;i&gt;Make sure you trust those extensions before enabling them!&lt;/i&gt;</source>
         <translation type="unfinished"></translation>
     </message>
     <message>

diff --git a/translations/tiled_bg.ts b/translations/tiled_bg.ts
@@ -4455,8 +4455,8 @@ Please select specific format.</source>
     </message>
     <message>
         <location line="+35"/>
-        <source>The current project contains &lt;a href=&quot;https://doc.mapeditor.org/en/stable/reference/scripting/&quot;&gt;scripted extensions&lt;/a&gt;.&lt;br&gt;&lt;i&gt;Make sure you trust those extensions before enabling them!&lt;/i&gt;</source>
-        <translation>Текущият проект съдържа &lt;a href=&quot;https://doc.mapeditor.org/en/stable/reference/scripting/&quot;&gt;скриптови разширения&lt;/a&gt;.&lt;br&gt;&lt;i&gt;Уверете се, че имате доверие на тези разширения, преди да ги включите!&lt;/i&gt;</translation>
+        <source>The current project contains &lt;a href=&quot;https://doc.mapeditor.org/en/stable/manual/scripting/&quot;&gt;scripted extensions&lt;/a&gt;.&lt;br&gt;&lt;i&gt;Make sure you trust those extensions before enabling them!&lt;/i&gt;</source>
+        <translation>Текущият проект съдържа &lt;a href=&quot;https://doc.mapeditor.org/en/stable/manual/scripting/&quot;&gt;скриптови разширения&lt;/a&gt;.&lt;br&gt;&lt;i&gt;Уверете се, че имате доверие на тези разширения, преди да ги включите!&lt;/i&gt;</translation>
     </message>
     <message>
         <location line="+3"/>

diff --git a/translations/tiled_cs.ts b/translations/tiled_cs.ts
@@ -4466,8 +4466,8 @@ Prosím vyberte formát ručně.</translation>
     </message>
     <message>
         <location line="+35"/>
-        <source>The current project contains &lt;a href=&quot;https://doc.mapeditor.org/en/stable/reference/scripting/&quot;&gt;scripted extensions&lt;/a&gt;.&lt;br&gt;&lt;i&gt;Make sure you trust those extensions before enabling them!&lt;/i&gt;</source>
-        <translation>Tento projekt obsahuje skriptová rozšíření (&lt;a href=&quot;https://doc.mapeditor.org/en/stable/reference/scripting/&quot;&gt;více informací  – anglicky)&lt;/a&gt;.&lt;br&gt;&lt;i&gt;Než tato rozšíření povolíte, ověřte si že jim věříte!&lt;/i&gt;</translation>
+        <source>The current project contains &lt;a href=&quot;https://doc.mapeditor.org/en/stable/manual/scripting/&quot;&gt;scripted extensions&lt;/a&gt;.&lt;br&gt;&lt;i&gt;Make sure you trust those extensions before enabling them!&lt;/i&gt;</source>
+        <translation>Tento projekt obsahuje skriptová rozšíření (&lt;a href=&quot;https://doc.mapeditor.org/en/stable/manual/scripting/&quot;&gt;více informací  – anglicky)&lt;/a&gt;.&lt;br&gt;&lt;i&gt;Než tato rozšíření povolíte, ověřte si že jim věříte!&lt;/i&gt;</translation>
     </message>
     <message>
         <location line="+3"/>

diff --git a/translations/tiled_de.ts b/translations/tiled_de.ts
@@ -4455,8 +4455,8 @@ Bitte Format angeben.</translation>
     </message>
     <message>
         <location line="+35"/>
-        <source>The current project contains &lt;a href=&quot;https://doc.mapeditor.org/en/stable/reference/scripting/&quot;&gt;scripted extensions&lt;/a&gt;.&lt;br&gt;&lt;i&gt;Make sure you trust those extensions before enabling them!&lt;/i&gt;</source>
-        <translation>Das aktuelle Projekt enthält &lt;a href=&quot;https://doc.mapeditor.org/en/stable/reference/scripting/&quot;&gt;Gescriptete Erweiterungen&lt;/a&gt;.&lt;br&gt;&lt;i&gt;Stellen Sie sicher, dass sie diesen Erweiterungen vertrauen können!!&lt;/i&gt;</translation>
+        <source>The current project contains &lt;a href=&quot;https://doc.mapeditor.org/en/stable/manual/scripting/&quot;&gt;scripted extensions&lt;/a&gt;.&lt;br&gt;&lt;i&gt;Make sure you trust those extensions before enabling them!&lt;/i&gt;</source>
+        <translation>Das aktuelle Projekt enthält &lt;a href=&quot;https://doc.mapeditor.org/en/stable/manual/scripting/&quot;&gt;Gescriptete Erweiterungen&lt;/a&gt;.&lt;br&gt;&lt;i&gt;Stellen Sie sicher, dass sie diesen Erweiterungen vertrauen können!!&lt;/i&gt;</translation>
     </message>
     <message>
         <location line="+3"/>

diff --git a/translations/tiled_en.ts b/translations/tiled_en.ts
@@ -4444,8 +4444,8 @@ Please select specific format.</translation>
     </message>
     <message>
         <location line="+35"/>
-        <source>The current project contains &lt;a href=&quot;https://doc.mapeditor.org/en/stable/reference/scripting/&quot;&gt;scripted extensions&lt;/a&gt;.&lt;br&gt;&lt;i&gt;Make sure you trust those extensions before enabling them!&lt;/i&gt;</source>
-        <translation>The current project contains &lt;a href=&quot;https://doc.mapeditor.org/en/stable/reference/scripting/&quot;&gt;scripted extensions&lt;/a&gt;.&lt;br&gt;&lt;i&gt;Make sure you trust those extensions before enabling them!&lt;/i&gt;</translation>
+        <source>The current project contains &lt;a href=&quot;https://doc.mapeditor.org/en/stable/manual/scripting/&quot;&gt;scripted extensions&lt;/a&gt;.&lt;br&gt;&lt;i&gt;Make sure you trust those extensions before enabling them!&lt;/i&gt;</source>
+        <translation>The current project contains &lt;a href=&quot;https://doc.mapeditor.org/en/stable/manual/scripting/&quot;&gt;scripted extensions&lt;/a&gt;.&lt;br&gt;&lt;i&gt;Make sure you trust those extensions before enabling them!&lt;/i&gt;</translation>
     </message>
     <message>
         <location line="+3"/>

diff --git a/translations/tiled_es.ts b/translations/tiled_es.ts
@@ -4452,7 +4452,7 @@ Por favor seleccione un formato específico.</translation>
     </message>
     <message>
         <location line="+35"/>
-        <source>The current project contains &lt;a href=&quot;https://doc.mapeditor.org/en/stable/reference/scripting/&quot;&gt;scripted extensions&lt;/a&gt;.&lt;br&gt;&lt;i&gt;Make sure you trust those extensions before enabling them!&lt;/i&gt;</source>
+        <source>The current project contains &lt;a href=&quot;https://doc.mapeditor.org/en/stable/manual/scripting/&quot;&gt;scripted extensions&lt;/a&gt;.&lt;br&gt;&lt;i&gt;Make sure you trust those extensions before enabling them!&lt;/i&gt;</source>
         <translation type="unfinished"></translation>
     </message>
     <message>

diff --git a/translations/tiled_fi.ts b/translations/tiled_fi.ts
@@ -4455,8 +4455,8 @@ Ole hyvä ja valitse tietty tiedostomuoto.</translation>
     </message>
     <message>
         <location line="+35"/>
-        <source>The current project contains &lt;a href=&quot;https://doc.mapeditor.org/en/stable/reference/scripting/&quot;&gt;scripted extensions&lt;/a&gt;.&lt;br&gt;&lt;i&gt;Make sure you trust those extensions before enabling them!&lt;/i&gt;</source>
-        <translation>Nykyinen projekti sisältää &lt;a href=&quot;https://doc.mapeditor.org/en/stable/reference/scripting/&quot;&gt;skriptattuja laajennuksia&lt;/a&gt;.&lt;br&gt;&lt;i&gt;Varmista, että luotat näihin laajennuksiin ennen kuin otat ne käyttöön!&lt;/i&gt;</translation>
+        <source>The current project contains &lt;a href=&quot;https://doc.mapeditor.org/en/stable/manual/scripting/&quot;&gt;scripted extensions&lt;/a&gt;.&lt;br&gt;&lt;i&gt;Make sure you trust those extensions before enabling them!&lt;/i&gt;</source>
+        <translation>Nykyinen projekti sisältää &lt;a href=&quot;https://doc.mapeditor.org/en/stable/manual/scripting/&quot;&gt;skriptattuja laajennuksia&lt;/a&gt;.&lt;br&gt;&lt;i&gt;Varmista, että luotat näihin laajennuksiin ennen kuin otat ne käyttöön!&lt;/i&gt;</translation>
     </message>
     <message>
         <location line="+3"/>

diff --git a/translations/tiled_fr.ts b/translations/tiled_fr.ts
@@ -4463,8 +4463,8 @@ Veuillez sélectionner un format spécifique.</translation>
     </message>
     <message>
         <location line="+35"/>
-        <source>The current project contains &lt;a href=&quot;https://doc.mapeditor.org/en/stable/reference/scripting/&quot;&gt;scripted extensions&lt;/a&gt;.&lt;br&gt;&lt;i&gt;Make sure you trust those extensions before enabling them!&lt;/i&gt;</source>
-        <translation>Le projet courant contient des &lt;a href=&quot;https://doc.mapeditor.org/fr/stable/reference/scripting/&quot;&gt;extensions scriptées&lt;/a&gt;.&lt;br&gt;&lt;i&gt;N&apos;activez que des extensions donc vous avez confiance!&lt;/i&gt;</translation>
+        <source>The current project contains &lt;a href=&quot;https://doc.mapeditor.org/en/stable/manual/scripting/&quot;&gt;scripted extensions&lt;/a&gt;.&lt;br&gt;&lt;i&gt;Make sure you trust those extensions before enabling them!&lt;/i&gt;</source>
+        <translation>Le projet courant contient des &lt;a href=&quot;https://doc.mapeditor.org/fr/stable/manual/scripting/&quot;&gt;extensions scriptées&lt;/a&gt;.&lt;br&gt;&lt;i&gt;N&apos;activez que des extensions donc vous avez confiance!&lt;/i&gt;</translation>
     </message>
     <message>
         <location line="+3"/>

diff --git a/translations/tiled_he.ts b/translations/tiled_he.ts
@@ -4444,7 +4444,7 @@ Please select specific format.</source>
     </message>
     <message>
         <location line="+35"/>
-        <source>The current project contains &lt;a href=&quot;https://doc.mapeditor.org/en/stable/reference/scripting/&quot;&gt;scripted extensions&lt;/a&gt;.&lt;br&gt;&lt;i&gt;Make sure you trust those extensions before enabling them!&lt;/i&gt;</source>
+        <source>The current project contains &lt;a href=&quot;https://doc.mapeditor.org/en/stable/manual/scripting/&quot;&gt;scripted extensions&lt;/a&gt;.&lt;br&gt;&lt;i&gt;Make sure you trust those extensions before enabling them!&lt;/i&gt;</source>
         <translation type="unfinished"></translation>
     </message>
     <message>

diff --git a/translations/tiled_hu.ts b/translations/tiled_hu.ts
@@ -4455,8 +4455,8 @@ Válasszon egy adott formátumot.</translation>
     </message>
     <message>
         <location line="+35"/>
-        <source>The current project contains &lt;a href=&quot;https://doc.mapeditor.org/en/stable/reference/scripting/&quot;&gt;scripted extensions&lt;/a&gt;.&lt;br&gt;&lt;i&gt;Make sure you trust those extensions before enabling them!&lt;/i&gt;</source>
-        <translation>A jelenlegi projekt &lt;a href=&quot;https://doc.mapeditor.org/en/stable/reference/scripting/&quot;&gt;parancsfájllal vezérelt kiterjesztéseket&lt;/a&gt; tartalmaz.&lt;br&gt;&lt;i&gt;Győződjön meg arról, hogy megbízik-e ezekben a kiterjesztésekben, mielőtt engedélyezi azokat!&lt;/i&gt;</translation>
+        <source>The current project contains &lt;a href=&quot;https://doc.mapeditor.org/en/stable/manual/scripting/&quot;&gt;scripted extensions&lt;/a&gt;.&lt;br&gt;&lt;i&gt;Make sure you trust those extensions before enabling them!&lt;/i&gt;</source>
+        <translation>A jelenlegi projekt &lt;a href=&quot;https://doc.mapeditor.org/en/stable/manual/scripting/&quot;&gt;parancsfájllal vezérelt kiterjesztéseket&lt;/a&gt; tartalmaz.&lt;br&gt;&lt;i&gt;Győződjön meg arról, hogy megbízik-e ezekben a kiterjesztésekben, mielőtt engedélyezi azokat!&lt;/i&gt;</translation>
     </message>
     <message>
         <location line="+3"/>