docs: Improve management commands documentation

- use different role for Weblate and Django commands
- render Weblate commands with weblate prefix so that full command is show
- add migrate documentation to cover differences from Django

Fixes #9253

docs/_ext/djangodocs.py

@@ -1,29 +1,53 @@
 """Sphinx plugins for Weblate documentation."""
 import re
 
+from docutils.nodes import literal
 from sphinx import addnodes
 from sphinx.domains.std import Cmdoption
 
 # RE for option descriptions without a '--' prefix
 simple_option_desc_re = re.compile(r"([-_a-zA-Z0-9]+)(\s*.*?)(?=,\s+(?:/|-|--)|$)")
 
 
+class WeblateCommandLiteral(literal):
+    def __init__(self, rawsource="", text="", *children, **attributes):
+        if not text:
+            text = "weblate "
+        super().__init__(rawsource, text, *children, **attributes)
+
+
 def setup(app):
     app.add_crossref_type(
         directivename="setting", rolename="setting", indextemplate="pair: %s; setting"
     )
+    app.add_object_type(
+        directivename="weblate-admin",
+        rolename="wladmin",
+        indextemplate="pair: %s; weblate admin command",
+        parse_node=parse_weblate_admin_node,
+        ref_nodeclass=WeblateCommandLiteral,
+    )
+    app.add_directive("weblate-admin-option", Cmdoption)
     app.add_object_type(
         directivename="django-admin",
         rolename="djadmin",
-        indextemplate="pair: %s; weblate admin command",
+        indextemplate="pair: %s; django-admin command",
         parse_node=parse_django_admin_node,
     )
-    app.add_directive("django-admin-option", Cmdoption)
 
 
-def parse_django_admin_node(env, sig, signode):
+def parse_weblate_admin_node(env, sig, signode):
     command = sig.split(" ")[0]
+    # Context for options
     env.ref_context["std:program"] = command
     title = f"weblate {sig}"
     signode += addnodes.desc_name(title, title)
     return command
+
+
+def parse_django_admin_node(env, sig, signode):
+    command = sig.split(" ")[0]
+    env.ref_context["std:program"] = command
+    title = "django-admin %s" % sig
+    signode += addnodes.desc_name(title, title)
+    return command

docs/admin/access.rst

@@ -612,7 +612,7 @@ List of teams
 ^^^^^^^^^^^^^^
 
 The following teams are created upon installation (or after executing
-:djadmin:`setupgroups`) and you are free to modify them. The migration will,
+:wladmin:`setupgroups`) and you are free to modify them. The migration will,
 however, re-create them if you delete or rename them.
 
 `Guests`

docs/admin/addons.rst

@@ -10,7 +10,7 @@ translation component.
 .. hint::
 
    You can also configure add-ons using :ref:`API <addons-api>`,
-   :setting:`DEFAULT_ADDONS`, or :djadmin:`install_addon`.
+   :setting:`DEFAULT_ADDONS`, or :wladmin:`install_addon`.
 
 .. image:: /screenshots/addons.png
 
@@ -322,7 +322,7 @@ Matching files:
 .. seealso::
 
    :ref:`markup`,
-   :djadmin:`import_project`
+   :wladmin:`import_project`
 
 .. _addon-weblate.flags.bulk:
 

docs/admin/auth.rst

@@ -586,7 +586,7 @@ Once you have the package installed, you can hook it into the Django authenticat
     ``'weblate.accounts.auth.WeblateUserBackend'`` is still needed in order to
     make permissions and facilitate anonymous users. It will also allow you
     to sign in using a local admin account, if you have created it (e.g. by using
-    :djadmin:`createadmin`).
+    :wladmin:`createadmin`).
 
 Using bind password
 ~~~~~~~~~~~~~~~~~~~

docs/admin/backup.rst

@@ -242,7 +242,7 @@ tools such as :program:`pg_dump` or :program:`mysqldump`. It usually performs
 better than Django backup, and it restores complete tables with all their data.
 
 You can restore this backup in a newer Weblate release, it will perform all the
-necessary migrations when running in :djadmin:`django:migrate`. Please consult
+necessary migrations when running in :wladmin:`migrate`. Please consult
 :doc:`upgrade` on more detailed info on how to upgrade between versions.
 
 Django database backup
@@ -256,7 +256,7 @@ Prior to restoring the database you need to be running exactly the same Weblate
 version the backup was made on. This is necessary as the database structure does
 change between releases and you would end up corrupting the data in some way.
 After installing the same version, run all database migrations using
-:djadmin:`django:migrate`.
+:wladmin:`migrate`.
 
 Afterwards some entries will already be created in the database and you
 will have them in the database backup as well. The recommended approach is to
@@ -366,7 +366,7 @@ Restoring manual backup
 
 1. Restore all data you have backed up.
 
-2. Update all repositories using :djadmin:`updategit`.
+2. Update all repositories using :wladmin:`updategit`.
 
    .. code-block:: sh
 

docs/admin/config.rst

@@ -343,7 +343,7 @@ You can turn on only a few:
 
     Changing this setting only affects newly changed translations. Existing checks
     will still be stored in the database. To also apply changes to the stored translations, run
-    :djadmin:`updatechecks`.
+    :wladmin:`updatechecks`.
 
 .. seealso::
 
@@ -371,7 +371,7 @@ Number of hours between committing pending changes by way of the background task
    :ref:`component`,
    :ref:`component-commit_pending_age`,
    :ref:`production-cron`,
-   :djadmin:`commit_pending`
+   :wladmin:`commit_pending`
 
 
 .. setting:: CONTACT_FORM
@@ -562,7 +562,7 @@ Example:
 
 .. seealso::
 
-   :djadmin:`install_addon`,
+   :wladmin:`install_addon`,
    :doc:`addons`,
    :setting:`WEBLATE_ADDONS`
 
@@ -1766,7 +1766,7 @@ UPDATE_LANGUAGES
 
 Controls whether languages database should be updated when running database
 migration and is on by default. This setting has no effect on invocation
-of :djadmin:`setuplang`.
+of :wladmin:`setuplang`.
 
 .. warning::
 

docs/admin/continuous.rst

@@ -65,7 +65,7 @@ source.
 
 * Enable :setting:`AUTO_UPDATE` to automatically update all components on your Weblate instance
 
-* Execute :djadmin:`updategit` (with selection of project or ``--all`` to update all)
+* Execute :wladmin:`updategit` (with selection of project or ``--all`` to update all)
 
 Whenever Weblate updates the repository, the post-update addons will be
 triggered, see :ref:`addons`.

docs/admin/install.rst

@@ -744,13 +744,9 @@ Filling up the database
 -----------------------
 
 After your configuration is ready, you can run
-:samp:`weblate migrate` to create the database structure. Now you should be
+:wladmin:`migrate` to create the database structure. Now you should be
 able to create translation projects using the admin interface.
 
-In case you want to run an installation non interactively, you can use
-:samp:`weblate migrate --noinput`, and then create an admin user using
-:djadmin:`createadmin` command.
-
 Once you are done, you should also check the :guilabel:`Performance report` in the
 admin interface, which will give you hints of potential non optimal configuration on your
 site.
@@ -1053,11 +1049,11 @@ For optimal performance, it is good idea to run some maintenance tasks in the
 background. This is now automatically done by :ref:`celery` and covers following tasks:
 
 * Configuration health check (hourly).
-* Committing pending changes (hourly), see :ref:`lazy-commit` and :djadmin:`commit_pending`.
+* Committing pending changes (hourly), see :ref:`lazy-commit` and :wladmin:`commit_pending`.
 * Updating component alerts (daily).
 * Update remote branches (nightly), see :setting:`AUTO_UPDATE`.
-* Translation memory backup to JSON (daily), see :djadmin:`dump_memory`.
-* Fulltext and database maintenance tasks (daily and weekly tasks), see :djadmin:`cleanuptrans`.
+* Translation memory backup to JSON (daily), see :wladmin:`dump_memory`.
+* Fulltext and database maintenance tasks (daily and weekly tasks), see :wladmin:`cleanuptrans`.
 
 .. versionchanged:: 3.2
 
@@ -1460,7 +1456,7 @@ Monitoring Celery status
 ++++++++++++++++++++++++
 
 You can find current length of the Celery task queues in the
-:ref:`management-interface` or you can use :djadmin:`celery_queues` on the
+:ref:`management-interface` or you can use :wladmin:`celery_queues` on the
 command-line. In case the queue will get too long, you will also get
 configuration error in the admin interface.
 
@@ -1478,7 +1474,7 @@ configuration error in the admin interface.
    :doc:`celery:userguide/workers`,
    :doc:`celery:userguide/daemonizing`,
    :doc:`celery:userguide/monitoring`,
-   :djadmin:`celery_queues`
+   :wladmin:`celery_queues`
 
 .. _monitoring:
 

docs/admin/languages.rst

@@ -13,13 +13,13 @@ Built-in language definitions
 
 Definitions for about 600 languages are included in Weblate and the list is
 extended in every release. Whenever Weblate is upgraded (more specifically
-whenever :program:`weblate migrate` is executed, see
+whenever :wladmin:`migrate` is executed, see
 :ref:`generic-upgrade-instructions`) the database of languages is updated to
 include all language definitions shipped in Weblate.
 
 This feature can be disable using :setting:`UPDATE_LANGUAGES`. You can also
 enforce updating the database to match Weblate built-in data using
-:djadmin:`setuplang`.
+:wladmin:`setuplang`.
 
 .. seealso::