From 0a187e3f2bdf3715775385a2b8d5131c06f8a648 Mon Sep 17 00:00:00 2001 From: Dusan Vuckovic Date: Fri, 22 Sep 2023 15:46:55 +0100 Subject: [PATCH] Fixes #360 - Create/consolidate aliases for all documentation parts for better linking. --- .rstcheck.cfg | 3 ++ admin/console/dangerzone-for-experts.rst | 6 +-- admin/console/working-on-ticket-articles.rst | 15 ++----- admin/console/working-on-tickets.rst | 21 ++++----- admin/console/working-on-users.rst | 6 +-- api/generic-cti/index.rst | 16 +++---- api/generic-cti/newcall-event.rst | 5 +-- api/intro.rst | 6 +-- api/object.rst | 7 +-- api/organization.rst | 8 ++-- api/user.rst | 26 ++++------- appendix/backup-and-restore/configuration.rst | 7 +-- appendix/backup-and-restore/migrate-hosts.rst | 18 +++----- .../backup-and-restore/troubleshooting.rst | 6 +-- appendix/configure-env-vars.rst | 3 +- appendix/privacy.rst | 4 +- appendix/reporting-tools-thirdparty.rst | 7 ++- appendix/single-sign-on.rst | 9 ++-- conf.py | 26 ++++++++++- contributing/start.rst | 16 ++++--- getting-started/first-steps.rst | 44 +++++++++---------- install/elasticsearch.rst | 5 +-- migration/freshdesk.rst | 20 ++++----- migration/kayako.rst | 20 ++++----- migration/zendesk.rst | 20 ++++----- prerequisites/software.rst | 9 ++-- 26 files changed, 147 insertions(+), 186 deletions(-) diff --git a/.rstcheck.cfg b/.rstcheck.cfg index 20f1db37..25717e3c 100644 --- a/.rstcheck.cfg +++ b/.rstcheck.cfg @@ -2,5 +2,8 @@ report_level=WARNING ignore_directives = tabs +ignore_roles= + admin-docs, + user-docs ignore_languages= json diff --git a/admin/console/dangerzone-for-experts.rst b/admin/console/dangerzone-for-experts.rst index ad7e586e..32243698 100644 --- a/admin/console/dangerzone-for-experts.rst +++ b/admin/console/dangerzone-for-experts.rst @@ -41,10 +41,8 @@ Removing users If you're not sure what to do and need to learn more about what Zammad does upon removing users, please consider using Zammad's UI options in stead. - Our documentation for the `data privacy`_ function will help you a lot! - -.. _data privacy: - https://admin-docs.zammad.org/en/latest/system/data-privacy.html + Our documentation for the :admin-docs:`data privacy ` + function will help you a lot! Removing users is possible in 2 ways: A single user and in bulk. diff --git a/admin/console/working-on-ticket-articles.rst b/admin/console/working-on-ticket-articles.rst index 2d617d1a..37669b1c 100644 --- a/admin/console/working-on-ticket-articles.rst +++ b/admin/console/working-on-ticket-articles.rst @@ -6,23 +6,16 @@ Working with ticket articles Count Public “Notes” toward SLAs -------------------------------- -Normally, `notes`_ don't count toward `service-level agreements`_. +Normally, :user-docs:`notes ` +don't count toward :admin-docs:`service-level agreements `. Use the following command to include publicly-visible notes when tracking SLA compliance. (Internal notes *will never* affect SLA calculations.) -.. _notes: - https://user-docs.zammad.org/en/latest/basics/service-ticket/follow-up.html#adding-new-messages-notes - -.. _service-level agreements: - https://admin-docs.zammad.org/en/latest/manage/slas.html - .. note:: By default, customers are not notified when public notes are added to a - ticket. Set up a `trigger`_ if you wish to change this behavior. - -.. _trigger: - https://admin-docs.zammad.org/en/latest/manage/trigger.html + ticket. Set up a :admin-docs:`trigger ` if you wish to + change this behavior. .. warning:: diff --git a/admin/console/working-on-tickets.rst b/admin/console/working-on-tickets.rst index f650d35b..8099876e 100644 --- a/admin/console/working-on-tickets.rst +++ b/admin/console/working-on-tickets.rst @@ -116,10 +116,8 @@ This will show all state types needed for creating new ticket states. *pending reminders* or *closed* states. State types also indicate the color scheme to be used. - You can learn more about that `in our user documentation`_. - -.. _in our user documentation: - https://user-docs.zammad.org/en/latest/basics/service-ticket/settings/state.html + You can learn more about that + :user-docs:`in our user documentation `. .. code-block:: ruby @@ -193,9 +191,10 @@ reached. (optional) Disable date and time picker (pending till) for pending states ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Starting with Zammad 5.0, `Core Workflows`_ automatically handles displaying the -"pending till" field for pending states. Below snippet *is not required* and is -only relevant if you don't want to create a workflow within the UI of Zammad. +Starting with Zammad 5.0, :admin-docs:`Core Workflows ` +automatically handles displaying the "pending till" field for pending states. +Below snippet *is not required* and is only relevant if you don't want to +create a workflow within the UI of Zammad. Replace ``pending customer feedback`` with the pending state of your choice. @@ -242,11 +241,9 @@ Limit available states for customers .. tip:: - `Core Workflows`_ allows you to achieve below described behavior any time - without any issues. No need to use the console if you don't want to! - -.. _Core Workflows: - https://admin-docs.zammad.org/en/latest/system/core-workflows.html + :admin-docs:`Core Workflows ` allows you to + achieve below described behavior any time without any issues. No need to use + the console if you don't want to! By default Zammad allows customers to change Ticket states to ``open`` and ``closed``. If this does not meet your requirenments, you can adjust this at diff --git a/admin/console/working-on-users.rst b/admin/console/working-on-users.rst index 3c3a4e56..3b2c5b8f 100644 --- a/admin/console/working-on-users.rst +++ b/admin/console/working-on-users.rst @@ -21,10 +21,8 @@ Unlock a locked user account .. tip:: Unlocking a locked user account is also supported by Zammad's web UI. - Please refer the `admin documentation`_ for more information. - -.. _admin documentation: - https://admin-docs.zammad.org/en/latest/manage/users/via-the-admin-panel.html + Please refer to the :admin-docs:`admin documentation ` + for more information. It sometimes happens that a user locks himself out by wildly trying the wrong password multiple times. Depending on your maximum failing login count diff --git a/api/generic-cti/index.rst b/api/generic-cti/index.rst index 222355ed..03d70a15 100644 --- a/api/generic-cti/index.rst +++ b/api/generic-cti/index.rst @@ -7,16 +7,15 @@ Features Here's a small condensed list of the possibilities this CTI API provides. Inbound - * `Caller log functions`_ for your agents. + * :user-docs:`Caller log functions ` for your + agents. * Blocking of CallerIDs during signaling. * - + Outbound - * `Caller log functions`_ for your agents. + * :user-docs:`Caller log functions ` for your + agents. * Set outbound caller IDs depending on the caller ID target. -.. _Caller log functions: - https://user-docs.zammad.org/en/latest/extras/caller-log.html - .. include:: /api/generic-cti/cti-endpoint-limitations.include.rst Endpoint @@ -28,16 +27,13 @@ Endpoint Generic CTI configuration and the correct endpoint can be found in your Zammad integration settings and are documented in our - `admin documentation`_. + :admin-docs:`admin documentation `. | Please also note the there listed requirements and limitations. | All options that require returns (e.g. blocking, manipulating outgoing caller IDs) rely on configurations within the Zammad CTI integration page. -.. _admin documentation: - https://admin-docs.zammad.org/en/latest/system/integrations/generic-cti.html - Events There are several events in terms of an ongoing call. These actions always come from your PBX system and may be: diff --git a/api/generic-cti/newcall-event.rst b/api/generic-cti/newcall-event.rst index c00d8ef4..83c8e36d 100644 --- a/api/generic-cti/newcall-event.rst +++ b/api/generic-cti/newcall-event.rst @@ -42,10 +42,7 @@ New call * - ``queue`` - e.g. ``support``, ``sales`` - An optional queue name, this option is relevant for the - `Caller Log Filter `_ - -.. _admin documentation: - https://admin-docs.zammad.org/en/latest/system/integrations/generic-cti.html + :admin-docs:`Caller Log Filter ` There's two options on how to ``POST`` the relevant data to Zammad. diff --git a/api/intro.rst b/api/intro.rst index 8c1cb681..54f5d7be 100644 --- a/api/intro.rst +++ b/api/intro.rst @@ -550,10 +550,8 @@ and user each. .. warning:: Please note that Core Workflows may restrict access to attributes or values. - see `Core Workflows limitations`_ to learn more. - -.. _Core Workflows limitations: - https://admin-docs.zammad.org/en/latest/system/core-workflows/limitations.html + See :admin-docs:`Core Workflows limitations ` + to learn more. Pagination ========== diff --git a/api/object.rst b/api/object.rst index 19b0dce4..deeb80f4 100644 --- a/api/object.rst +++ b/api/object.rst @@ -7,11 +7,8 @@ Object Proceed with absolute caution and ensure to adjust any of Zammads default fields. - If you want to hide fields, consider `Core Workflows`_ instead. - For states and priorities use either API endpoints or rails console. - -.. _Core Workflows: - https://admin-docs.zammad.org/en/latest/system/core-workflows.html + If you want to hide fields, consider :admin-docs:`Core Workflows ` + instead. For states and priorities use either API endpoints or rails console. List ==== diff --git a/api/organization.rst b/api/organization.rst index 6d478165..0105457c 100644 --- a/api/organization.rst +++ b/api/organization.rst @@ -313,7 +313,7 @@ Response: ], "secondary_member_ids": [] } - + Delete ====== @@ -327,10 +327,8 @@ Required permission: ``admin.organization`` is not possible via API - this will be indicated by ``"error": "Can't delete, object has references."``. This is *not* a bug. - Consider using `Data Privacy`_ via UI for more control instead. - -.. _Data Privacy: - https://admin-docs.zammad.org/en/latest/system/data-privacy.html + Consider using :admin-docs:`Data Privacy ` via UI + for more control instead. ``DELETE``-Request sent: ``/api/v1/organizations/{id}`` diff --git a/api/user.rst b/api/user.rst index 6d3e4ef8..ca8993bb 100644 --- a/api/user.rst +++ b/api/user.rst @@ -7,10 +7,8 @@ User ``ticket.agent`` permissions. Some attributes / information may not be available in specific situations. - Please see our `Permission Guide`_ to get better insights. - -.. _Permission Guide: - https://admin-docs.zammad.org/en/latest/manage/roles/index.html#reference-guide-permissions + Please see our :admin-docs:`Permission Guide ` + to get better insights. me - current user ================= @@ -1181,21 +1179,15 @@ Create ====== Required permission: ``admin.user`` **or** ``ticket.agent`` - + .. note:: **🤓 This depends on permissions** Agents can't set user passwords, roles or group permission. Instead - Zammad will apply to `default sign up role`_. + Zammad will apply to :admin-docs:`default sign up role `. Technically unauthenticated user creation is possible if you manage to provide the required CSRF token (out of scope of this documentation). - If you don't want that, consider `disabling user registration`_. - -.. _default sign up role: - https://admin-docs.zammad.org/en/latest/manage/roles/index.html#role-details - -.. _disabling user registration: - https://admin-docs.zammad.org/en/latest/settings/security/base.html + If you don't want that, consider :admin-docs:`disabling user registration `. .. tip:: **🧐 Creation payloads can be big** @@ -1332,7 +1324,7 @@ Required permission: ``admin.user`` **or** ``ticket.agent`` .. note:: **🤓 This depends on permissions** Agents can't set user passwords, roles or group permission. Instead - Zammad will apply to `default sign up role`_. + Zammad will apply to :admin-docs:`default sign up role `. ``PUT``-Request sent: ``/api/v1/users/{id}`` @@ -1464,10 +1456,8 @@ Required permission: ``admin.user`` via API - this will be indicated by ``"error": "Can't delete, object has references."``. This is *not* a bug. - Consider using `Data Privacy`_ via UI for more control instead. - -.. _Data Privacy: - https://admin-docs.zammad.org/en/latest/system/data-privacy.html + Consider using :admin-docs:`Data Privacy ` via UI + for more control instead. ``DELETE``-Request sent: ``/api/v1/users/{id}`` diff --git a/appendix/backup-and-restore/configuration.rst b/appendix/backup-and-restore/configuration.rst index 9244dd8a..52f62dc5 100644 --- a/appendix/backup-and-restore/configuration.rst +++ b/appendix/backup-and-restore/configuration.rst @@ -67,11 +67,8 @@ After this you'll be ready to continue with either Zammad database together with the attachments you've stored within the file system. - Please refer `Storage Settings`_ to learn how to change the - storage location of your attachments. - -.. _Storage Settings: - https://admin-docs.zammad.org/en/latest/settings/system/storage.html + Please refer :admin-docs:`Storage Settings ` + to learn how to change the storage location of your attachments. ``DEBUG`` Default: ``no`` (accepts: ``yes`` or ``no``) diff --git a/appendix/backup-and-restore/migrate-hosts.rst b/appendix/backup-and-restore/migrate-hosts.rst index 9c59fcc0..bded5bc3 100644 --- a/appendix/backup-and-restore/migrate-hosts.rst +++ b/appendix/backup-and-restore/migrate-hosts.rst @@ -46,10 +46,7 @@ Step 2: Install Zammad on the destination host Step 3: Activate maintenance mode This ends agents and customers sessions. - `Learn more about the maintenance mode in Zammad`_. - -.. _Learn more about the maintenance mode in Zammad: - https://admin-docs.zammad.org/en/latest/system/maintenance.html + Learn more about :admin-docs:`the maintenance mode in Zammad `. Step 4: Disable your communication channels This is just a safety measurement. As our restore scripts starts Zammad @@ -205,20 +202,15 @@ Step 11: Re-enable Channels and deactivate maintenance mode After verifying the functionality of your channels, allow your agents and customers back in by disabling the maintenance mode. - `Learn more about the maintenance mode in Zammad`_. + Learn more about :admin-docs:`the maintenance mode in Zammad `. .. hint:: *Migrated from Zammad SaaS or switching providers?* - Please make sure that your `notification`_ and `FQDN`_ configuration - is still correct. Other wise you may have unexpected issues like not + Please make sure that your :admin-docs:`notification ` + and :admin-docs:`FQDN ` configuration is + still correct. Other wise you may have unexpected issues like not receiving notifications or non functional authentications (3rd party). -.. _notification: - https://admin-docs.zammad.org/en/latest/channels/email/accounts/email-notification.html - -.. _FQDN: - https://admin-docs.zammad.org/en/latest/settings/system/base.html - Step 12 (optional): Update Zammad to latest possible version In case the backup source was not on the latest possible version, please update your Zammad installation now. diff --git a/appendix/backup-and-restore/troubleshooting.rst b/appendix/backup-and-restore/troubleshooting.rst index 2a32dfb9..e2a91cfc 100644 --- a/appendix/backup-and-restore/troubleshooting.rst +++ b/appendix/backup-and-restore/troubleshooting.rst @@ -79,11 +79,9 @@ Here's some classics you may encounter. This warning will be shown once before creating an empty directory to allow the backup process to continue successfully. - If you believe that this is an error, please see `Storage Settings`_. + If you believe that this is an error, please see + :admin-docs:`Storage Settings `. In case the issue posts, please consult the `Zammad Community`_. -.. _Storage Settings: - https://admin-docs.zammad.org/en/latest/settings/system/storage.html - .. _Zammad Community: https://community.zammad.org/c/trouble-running-zammad-this-is-your-place/5 diff --git a/appendix/configure-env-vars.rst b/appendix/configure-env-vars.rst index b05a377d..bccc5645 100644 --- a/appendix/configure-env-vars.rst +++ b/appendix/configure-env-vars.rst @@ -40,8 +40,7 @@ General Options APP_RESTART_CMD The command Zammad will use to automatically restart the server - after `changes have been made in the Object Manager - `_. + after :admin-docs:`changes have been made in the Object Manager `. (*E.g.,* ``"systemctl restart zammad"``) If this is undefined, you will have to restart manually diff --git a/appendix/privacy.rst b/appendix/privacy.rst index 66876c9d..02a86ce1 100644 --- a/appendix/privacy.rst +++ b/appendix/privacy.rst @@ -12,12 +12,12 @@ Tickets and users By default, Zammad never automatically deletes tickets or users. To enable **automatic** deletion of tickets after a given interval, - `use the scheduler `_. + :admin-docs:`use the scheduler `. To **manually** delete users and all their associated tickets (*e.g.* in compliance with a “Right to Forget” request under the GDPR), you can use the - `data privacy functions `_ + :admin-docs:`data privacy functions ` in the admin panel or :doc:`use the console `. diff --git a/appendix/reporting-tools-thirdparty.rst b/appendix/reporting-tools-thirdparty.rst index 9ad50a6d..fc2f4407 100644 --- a/appendix/reporting-tools-thirdparty.rst +++ b/appendix/reporting-tools-thirdparty.rst @@ -13,10 +13,9 @@ This guide will discuss how to set up third party reporting tools with Zammad. .. IGNORE THE NEXT BLOCK - This functionality is not yet available. .. note:: **💰 Availability** - The following information require either a self-hosted installation or - a hosted instance with **PLUS** package. If you're a Hosted user, please - also check `the Elasticsearch integration - `_ + The following information require either a self-hosted installation or + a hosted instance with **PLUS** package. If you're a Hosted user, please + also check :admin-docs:`the Elasticsearch integration ` page for information on how to hook your tool to the index. Getting Started diff --git a/appendix/single-sign-on.rst b/appendix/single-sign-on.rst index 032f97c3..ba822b96 100644 --- a/appendix/single-sign-on.rst +++ b/appendix/single-sign-on.rst @@ -28,9 +28,8 @@ so that anyone with an account on your local intranet will .. note:: If you *don’t* have this IT infrastructure but still want one-click login, - see `Third-Party Authentication`_ for alternatives. - - .. _Third-Party Authentication: https://admin-docs.zammad.org/en/latest/settings/security.html#third-party-applications + see :admin-docs:`Third-Party Authentication ` + for alternatives. How does it work? ^^^^^^^^^^^^^^^^^ @@ -92,12 +91,10 @@ You will need: * some familiarity with system administration (*e.g.,* Apache configuration) -For best results, set up `LDAP integration`_ +For best results, set up :admin-docs:`LDAP integration ` to make sure your Active Directory and Zammad user accounts are always in sync. -.. _LDAP integration: https://admin-docs.zammad.org/en/latest/system/integrations/ldap.html - .. _sso-register-spn: Step 1: Configure Active Directory diff --git a/conf.py b/conf.py index 70e9290a..468d9671 100644 --- a/conf.py +++ b/conf.py @@ -13,7 +13,11 @@ source_suffix = '.rst' master_doc = 'index' exclude_patterns = ['_build', 'html', 'doctrees'] -extensions = ['versionwarning.extension', 'sphinx_tabs.tabs'] +extensions = [ + 'versionwarning.extension', + 'sphinx_tabs.tabs', + 'sphinx.ext.extlinks', +] locale_dirs = ['locale/'] gettext_compact = False @@ -89,3 +93,23 @@ 'title="Updating Zammad">Updating Zammad asap.' ), } + +# Provide aliases to common external documentation targets. +# It supports automatic substitution for the current branch placeholders, +# but always links to the English translation. +# +# :admin-docs:`the administrator documentation ` +# :user-docs:`the user documentation ` +# +# which may render the following links: +# +# https://admin-docs.zammad.org/en/pre-release/manage/users/index.html +# https://user-docs.zammad.org/en/latest/advanced/tabs.html +# +# Note the need for including the file extension as part of the path +# relative to the documentation root! +# +extlinks = { + 'admin-docs': (f'https://admin-docs.zammad.org/en/{branch}%s', ''), + 'user-docs': (f'https://user-docs.zammad.org/en/{branch}%s', ''), +} diff --git a/contributing/start.rst b/contributing/start.rst index 5c724a13..e1c6eafe 100644 --- a/contributing/start.rst +++ b/contributing/start.rst @@ -221,11 +221,17 @@ documentation projects (see RestructuredText_ for details): which is shown as link. This part can be translated. The path/to/document may not be translated, otherwise the link would not work anymore. -\`some text \`\_ - This is a link which can refer to a documentation page or an external - website. "some text" is the displayed text in the documentation, the part - between \< and \> is the link target. The \_ at the end is important and must - remain in the translated text. +\`some text \`\_ + This is a link which can refer to an external website. "some text" is the + displayed text in the documentation, the part between \< and \> is the link + target. The \_ at the end is important and must remain in the translated + text. + +\:admin-docs:\`some text \` + This is a link which refers to external documentation. "some text" is the + displayed text in the documentation, the part between \< and \> is the link + target. Note the absence of \_ at the end, since this link is using a + different construction mechanism. \**example string** Markup for text (e.g. bold, italics). Alternative: \*example string\*. diff --git a/getting-started/first-steps.rst b/getting-started/first-steps.rst index 5b1eebcb..cddfac65 100644 --- a/getting-started/first-steps.rst +++ b/getting-started/first-steps.rst @@ -1,7 +1,7 @@ First steps *********** -After successfully installing Zammad you'll have a couple of options. +After successfully installing Zammad you'll have a couple of options. * :doc:`Migrate from a supported source ` * :ref:`Restore Zammad from an existing backup ` @@ -10,8 +10,8 @@ After successfully installing Zammad you'll have a couple of options. Getting Started Wizard ---------------------- -If you visit Zammads web page the first time, you'll be greeted by its -Getting Started Wizard. It will guide you through the first most important +If you visit Zammad's web page the first time, you'll be greeted by its +Getting Started Wizard. It will guide you through the first most important things. .. figure:: /images/getting-started/wizard.gif @@ -20,7 +20,7 @@ things. :align: center .. - About this section: Below part uses definition list instead of field lists + About this section: Below part uses definition list instead of field lists intentionally. It's supposed to safe width for better readability. Step 1: Create your very first administrator account @@ -35,22 +35,22 @@ Step 1: Create your very first administrator account * contains at least one digit Step 2: Provide company information - You can upload a custom logo fitting to your company here. - The instance address is detected automatically and only required adjustment + You can upload a custom logo fitting to your company here. + The instance address is detected automatically and only required adjustment in case it's detected wrong. - All of these settings can be changed within - `Branding `_ and - `System `_ settings. + All of these settings can be changed within + :admin-docs:`Branding ` and + :admin-docs:`System ` settings. Step 3: E-Mail notification channel - By default Zammad uses sendmail - if that doesn't fit you can change it to + By default Zammad uses sendmail - if that doesn't fit you can change it to SMTP here. .. warning:: - Zammad uses ``noreply@`` as sender address by default. - SMTP setups might fail - you may want to skip this step with choosing + Zammad uses ``noreply@`` as sender address by default. + SMTP setups might fail - you may want to skip this step with choosing ``sendmail`` at this point. You can adjust it later! Step 4: Your first email channel (optional) @@ -58,13 +58,13 @@ Step 4: Your first email channel (optional) .. warning:: - Zammad reacts to fetched emails by default. + Zammad reacts to fetched emails by default. If that's not what you want, skip this step for now. Learn more about the email channel within the documentation for - `email channels `_. + :admin-docs:`email channels `. -After finishing the wizard you'll be automatically logged in to the just created account. +After finishing the wizard you'll be automatically logged in to the just created account. .. figure:: /images/getting-started/dashboard-with-clues.png :alt: First time on the dashboard will provide a small clue intro @@ -74,9 +74,9 @@ After finishing the wizard you'll be automatically logged in to the just created Further Steps ------------- -In our opinion the next step order would like below sample. -You can skip parts you don't need or adapt. All parts are described within -`Zammads admin documentation `_. +In our opinion the next step order would like below sample. +You can skip parts you don't need or adapt. All parts are described within +:admin-docs:`Zammad's admin documentation `. #. Configure your required groups #. Adjust triggers as needed @@ -89,8 +89,8 @@ You can skip parts you don't need or adapt. All parts are described within #. Configure roles if needed #. Consider Third Party logins or LDAP integration for easier logins #. Add agent accounts (users) - #. Consider backup strategies for Zammad. - See :doc:`/appendix/backup-and-restore/index` + #. Consider backup strategies for Zammad, see + :doc:`/appendix/backup-and-restore/index` From point 5 on you'll be able to work productive in theory. 🙌 @@ -98,6 +98,6 @@ From point 5 on you'll be able to work productive in theory. 🙌 **😖 Are you still lost?** - If above list doesn't help you or you'll need to jump in a lot faster, - you can also get Workshops with one of our + If above list doesn't help you or you'll need to jump in a lot faster, + you can also get Workshops with one of our `Zammad consultants `_. diff --git a/install/elasticsearch.rst b/install/elasticsearch.rst index df148a98..4dfb60ca 100644 --- a/install/elasticsearch.rst +++ b/install/elasticsearch.rst @@ -242,9 +242,8 @@ Optional settings certificates?** You can import custom certificates and custom CA certificates to - Zammad. Please have a look `here - `_ - in the admin documentation. + Zammad. Please have a look + :admin-docs:`in the admin documentation `. Appendix ======== diff --git a/migration/freshdesk.rst b/migration/freshdesk.rst index bd980e0f..fa4c9a26 100644 --- a/migration/freshdesk.rst +++ b/migration/freshdesk.rst @@ -4,7 +4,7 @@ From Freshdesk Limitations =========== -Please note below Freshdesk specific limitations. +Please note below Freshdesk specific limitations. These are additional limitations to the :ref:`general ones listed `. @@ -16,10 +16,8 @@ These are additional limitations to the * Due to API limitations Zammad will not show the total number of objects to import, but instead correct them in steps of ``100``. * User passwords are not migrated and will require the user to use the - `password reset link`_ on the login page. - -.. _password reset link: - https://admin-docs.zammad.org/en/latest/settings/security/base.html#lost-password + :admin-docs:`password reset link ` + on the login page. .. note:: @@ -53,7 +51,7 @@ consider using the console over the browser version. .. tab:: Via browser After installing Zammad and configuring your - :doc:`webserver `, navigate to your + :doc:`webserver `, navigate to your Zammads FQDN in your browser and follow the migration wizard. Depending on the number of users, tickets and Freshdesk plan this may take @@ -116,7 +114,7 @@ consider using the console over the browser version. Running the following command in a rails console will provide detailed state information of your migration. - + .. code-block:: ruby pp ImportJob.find_by(name: 'Import::Freshdesk') @@ -259,14 +257,12 @@ After migration =============== As the migration technically skips the getting started wizard, please -note that you want to adjust your `FQDN settings`_ (FQDN & HTTP-Type). +note that you want to adjust your +:admin-docs:`FQDN settings ` (FQDN & HTTP-Type). .. include:: /migration/includes/how-to-login.include.rst - -.. _FQDN settings: - https://admin-docs.zammad.org/en/latest/settings/system/base.html -After successfully migrating your Freshdesk instance, +After successfully migrating your Freshdesk instance, continue with :doc:`/getting-started/first-steps`. .. include:: /migration/includes/restarting-from-scratch.include.rst diff --git a/migration/kayako.rst b/migration/kayako.rst index 834888d5..7cccba7e 100644 --- a/migration/kayako.rst +++ b/migration/kayako.rst @@ -4,7 +4,7 @@ From Kayako Limitations =========== -Please note below Kayako specific limitations. +Please note below Kayako specific limitations. These are additional limitations to the :ref:`general ones listed `. @@ -22,10 +22,8 @@ These are additional limitations to the * **Important:** Please note that migration speed highly depends on your Kayako plan (API rate limits apply). * User passwords are not migrated and will require the user to use the - `password reset link`_ on the login page. - -.. _password reset link: - https://admin-docs.zammad.org/en/latest/settings/security/base.html#lost-password + :admin-docs:`password reset link ` + on the login page. .. note:: @@ -55,7 +53,7 @@ consider using the console over the browser version. .. tab:: Via browser After installing Zammad and configuring your - :doc:`webserver `, navigate to your + :doc:`webserver `, navigate to your Zammads FQDN in your browser and follow the migration wizard. Depending on the number of users, tickets and Kayako plan this may take @@ -120,7 +118,7 @@ consider using the console over the browser version. Running the following command in a rails console will provide detailed state information of your migration. - + .. code-block:: ruby pp ImportJob.find_by(name: 'Import::Kayako') @@ -263,7 +261,8 @@ After migration =============== As the migration technically skips the getting started wizard, please -note that you want to adjust your `FQDN settings`_ (FQDN & HTTP-Type). +note that you want to adjust your +:admin-docs:`FQDN settings ` (FQDN & HTTP-Type). .. hint:: @@ -275,11 +274,8 @@ note that you want to adjust your `FQDN settings`_ (FQDN & HTTP-Type). All other users will have to use the password reset function or login methods like LDAP or one click logins. - -.. _FQDN settings: - https://admin-docs.zammad.org/en/latest/settings/system/base.html -After successfully migrating your Kayako instance, +After successfully migrating your Kayako instance, continue with :doc:`/getting-started/first-steps`. .. include:: /migration/includes/restarting-from-scratch.include.rst diff --git a/migration/zendesk.rst b/migration/zendesk.rst index 8fd7a4d4..51c80df8 100644 --- a/migration/zendesk.rst +++ b/migration/zendesk.rst @@ -4,7 +4,7 @@ From Zendesk Limitations =========== -Please note below Zendesk specific limitations. +Please note below Zendesk specific limitations. These are additional limitations to the :ref:`general ones listed `. @@ -14,10 +14,8 @@ These are additional limitations to the * **Important:** Please note that migration speed highly depends on your Zendesk plan (API rate limits apply). * User passwords are not migrated and will require the user to use the - `password reset link`_ on the login page. - -.. _password reset link: - https://admin-docs.zammad.org/en/latest/settings/security/base.html#lost-password + :admin-docs:`password reset link ` + on the login page. .. note:: @@ -51,7 +49,7 @@ consider using the console over the browser version. .. tab:: Via browser After installing Zammad and configuring your - :doc:`webserver `, navigate to your + :doc:`webserver `, navigate to your Zammads FQDN in your browser and follow the migration wizard. Depending on the number of users, tickets and Zendesk plan this may take @@ -116,7 +114,7 @@ consider using the console over the browser version. Running the following command in a rails console will provide detailed state information of your migration. - + .. code-block:: ruby pp ImportJob.find_by(name: 'Import::Zendesk') @@ -259,14 +257,12 @@ After migration =============== As the migration technically skips the getting started wizard, please -note that you want to adjust your `FQDN settings`_ (FQDN & HTTP-Type). +note that you want to adjust your +:admin-docs:`FQDN settings ` (FQDN & HTTP-Type). .. include:: /migration/includes/how-to-login.include.rst - -.. _FQDN settings: - https://admin-docs.zammad.org/en/latest/settings/system/base.html -After successfully migrating your Zendesk instance, +After successfully migrating your Zendesk instance, continue with :doc:`/getting-started/first-steps`. .. include:: /migration/includes/restarting-from-scratch.include.rst diff --git a/prerequisites/software.rst b/prerequisites/software.rst index c85b0b9f..187f6a9e 100644 --- a/prerequisites/software.rst +++ b/prerequisites/software.rst @@ -53,12 +53,9 @@ and thus should be avoided. .. note:: - The "Core workflows" feature of Zammad comes with an `Ajax Mode`_ which - can be activated separately in case you're having issues with field - selections. - -.. _Ajax Mode: - https://admin-docs.zammad.org/en/latest/settings/system/frontend.html + The "Core workflows" feature of Zammad comes with an + :admin-docs:`AJAX Mode ` which can be + activated separately in case you're having issues with field selections. 2. Server requirements ======================