From 86809d9301b37f536c130625f1a3ec6e8b204435 Mon Sep 17 00:00:00 2001 From: JC Brand Date: Fri, 22 Nov 2019 12:57:51 +0100 Subject: [PATCH] Fix RsT errors in docs and rename `html` recipe to `doc` --- Makefile | 7 ++- docs/source/configuration.rst | 98 +++++++++++++++++++---------------- docs/source/features.rst | 11 ++-- docs/source/translations.rst | 8 +-- 4 files changed, 68 insertions(+), 56 deletions(-) diff --git a/Makefile b/Makefile index d45d3bd58..03641e64e 100644 --- a/Makefile +++ b/Makefile @@ -40,7 +40,7 @@ help: @echo " check Run all tests." @echo " dev Set up the development environment and build unminified resources. To force a fresh start, run 'make clean' first." @echo " devserver Set up the development environment and start the webpack dev server." - @echo " html Make standalone HTML files of the documentation." + @echo " doc Make standalone HTML files of the documentation." @echo " po Generate gettext PO files for each i18n language." @echo " pot Generate a gettext POT file to be used for translations." @echo " release Prepare a new release of converse.js. E.g. make release VERSION=0.9.5" @@ -216,7 +216,10 @@ check: eslint dev docsdev: ./bin/activate .installed.cfg .PHONY: html -html: stamp-npm docsdev apidoc +html: doc + +.PHONY: doc +doc: stamp-npm docsdev apidoc rm -rf $(BUILDDIR)/html $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html make apidoc diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst index f7c656746..d9b7ae515 100644 --- a/docs/source/configuration.rst +++ b/docs/source/configuration.rst @@ -319,20 +319,20 @@ in to their XMPP account. .. note:: -The interaction between ``keepalive`` and ``auto_login`` is unfortunately -inconsistent depending on the ``authentication`` method used. + The interaction between ``keepalive`` and ``auto_login`` is unfortunately + inconsistent depending on the ``authentication`` method used. -If ``auto_login`` is set to ``false`` and ``authentication`` is set to -``anonymous``, ``external`` or ``prebind``, then Converse won't automatically -log the user in. + If ``auto_login`` is set to ``false`` and ``authentication`` is set to + ``anonymous``, ``external`` or ``prebind``, then Converse won't automatically + log the user in. -If ``authentication`` set to ``login`` the situation is much more -ambiguous, since we don't have a way to distinguish between wether we're -restoring a previous session (``keepalive``) or whether we're -automatically setting up a new session (``auto_login``). + If ``authentication`` set to ``login`` the situation is much more + ambiguous, since we don't have a way to distinguish between wether we're + restoring a previous session (``keepalive``) or whether we're + automatically setting up a new session (``auto_login``). -So currently if EITHER ``keepalive`` or ``auto_login`` is ``true`` and -``authentication`` is set to ``login``, then Converse will try to log the user in. + So currently if EITHER ``keepalive`` or ``auto_login`` is ``true`` and + ``authentication`` is set to ``login``, then Converse will try to log the user in. auto_away @@ -697,19 +697,23 @@ The placeholder text shown in the domain input on the registration form. emoji_categories ---------------- -* Default::: - { - "smileys": ":grinning:", - "people": ":thumbsup:", - "activity": ":soccer:", - "travel": ":motorcycle:", - "objects": ":bomb:", - "nature": ":rainbow:", - "food": ":hotdog:", - "symbols": ":musical_note:", - "flags": ":flag_ac:", - "custom": ":converse:" - } +* Default: + +:: + + { + "smileys": ":grinning:", + "people": ":thumbsup:", + "activity": ":soccer:", + "travel": ":motorcycle:", + "objects": ":bomb:", + "nature": ":rainbow:", + "food": ":hotdog:", + "symbols": ":musical_note:", + "flags": ":flag_ac:", + "custom": ":converse:" + } + This setting lets you define the categories that are available in the emoji picker, as well as the default image that's shown for each category. @@ -732,19 +736,23 @@ entries to the map under the ``custom`` key. emoji_categories_label ---------------------- -* Default::: - { - "smileys": "Smileys and emotions", - "people": "People", - "activity": "Activities", - "travel": "Travel", - "objects": "Objects", - "nature": "Animals and nature", - "food": "Food and drink", - "symbols": "Symbols", - "flags": "Flags", - "custom": "Stickers" - } +* Default: + +:: + + { + "smileys": "Smileys and emotions", + "people": "People", + "activity": "Activities", + "travel": "Travel", + "objects": "Objects", + "nature": "Animals and nature", + "food": "Food and drink", + "symbols": "Symbols", + "flags": "Flags", + "custom": "Stickers" + } + This setting lets you pass in the text value that goes into the `title` attribute for the emoji categories. These strings will be translated, but for @@ -907,9 +915,6 @@ therefore what may be given as value for the :ref:`i18n` option. Any other locales will be ignored. -When self-hosting, also make sure that the locales are served and therefore -fetchable (via ``XMLHttpRequest``) at the URL specified by :ref:`locales-url`. - locked_domain ------------- @@ -966,15 +971,15 @@ muc_mention_autocomplete_filter * Default: ``contains`` -The method used for filtering MUC participants when using auto-complete. +The method used for filtering MUC participants when using auto-complete. Valid values are ``contains`` and ``starts_with``. muc_mention_autocomplete_show_avatar -------------------------------- +------------------------------------ * Default: ``true`` -Show avatars of MUC participants when using auto-complete. +Show avatars of MUC participants when using auto-complete. message_archiving ----------------- @@ -1271,8 +1276,7 @@ nickname is mentioned in a chatroom. Inside the ``./sounds`` directory of the Converse repo you'll see MP3 and Ogg formatted sound files. We need both, because neither format is supported by all browsers. -You can set the URL where the sound files are hosted with the `sounds_path`_ -option. +You can set the URL where the sound files are hosted with the `sounds_path`_ option. Requires the `src/converse-notification.js` plugin. @@ -1329,10 +1333,12 @@ providers_link The hyperlink on the registration form which points to a directory of public XMPP servers. +.. _`assets_path`: + assets_path ----------- -* Default: The `publicPath `_ value configured in the relevant Webpack configuration. +* Default: ``'/dist/'`` or the `publicPath `_ value as configured in the relevant Webpack configuration. Since version 5.0.0, Converse serves a smaller bundle by extracting various resources (for example emojis and translations) into separate files (aka diff --git a/docs/source/features.rst b/docs/source/features.rst index f348ac422..1645685c3 100644 --- a/docs/source/features.rst +++ b/docs/source/features.rst @@ -137,10 +137,13 @@ For more info, refer to the :ref:`show-desktop-notifications` configuration sett Multilingual Support ==================== -Converse is translated into multiple languages. Translations are supplied in -JSON format and are loaded on demand. Converse will expect to find the -translations in the ``/locales`` path of your site. This can be changed via the -:ref:`locales-url` configuration setting. +Converse is translated into over 30 languages. Translations can be added or +updated on `Weblate `_. + +Translations are supplied in JSON format and are loaded on demand. Converse will expect to find the +translations in the ``/dist/locales`` path of your site. This path can be +changed via the :ref:`assets_path` configuration setting. + Moderating chatrooms ==================== diff --git a/docs/source/translations.rst b/docs/source/translations.rst index 32fe87567..62315cbb0 100644 --- a/docs/source/translations.rst +++ b/docs/source/translations.rst @@ -18,14 +18,14 @@ directory, or through the web at `weblate