Use global.rst hyperlink definition.

Automated edit done by: https://github.com/ypid/ypid-ansible-common/blob/1a1128714b2bedb0ae427b8e4879084542558117/bin/sphinx-inline
Some changes had to be manually reverted to make the build pass (e. g.
  variable not defined in this single docs context).

Related to: debops/docs#155

.gitignore

@@ -21,3 +21,4 @@ docs/Makefile
 docs/_build/
 docs/conf.py
 docs/defaults.rst
+docs/includes/global.rst

README.rst

@@ -68,7 +68,7 @@ Here are a few services that are available
 Overview of how playbooks work within DebOps
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-There's a ``common.yml`` playbook which gets ran on every host except localhost.
+There's a :file:`common.yml` playbook which gets ran on every host except localhost.
 This includes standard services like sshd and ferm. The full list can be
 found `here <https://github.com/debops/debops-playbooks/blob/master/playbooks/common.yml>`_.
 

docs/custom-environment.rst

@@ -1,6 +1,8 @@
 Playbook environment variables
 ==============================
 
+.. include:: includes/all.rst
+
 In certain situations, for example on a network where direct Internet access is
 not allowed and users are required to use a HTTP proxy, you might need to
 define a custom set of environment variables for Ansible to execute playbooks.
@@ -24,16 +26,16 @@ playbooks included in this repository. The more specific variables override the
 more general ones, just as normal Ansible variables.
 
 The environment variables defined using these YAML dictionaries have only
-effect during the ``ansible-playbook`` run. Normal ``ansible`` commands as well
+effect during the :command:`ansible-playbook` run. Normal :command:`ansible` commands as well
 as commands/services executed on remote hosts will not use them. To configure
 desired environment variables on remote hosts, you might wan to check the
-``debops.resources`` Ansible role.
+debops.resources_ Ansible role.
 
 Examples
 --------
 
 To configure a HTTP proxy which should be used by Ansible roles on all hosts,
-add in the ``ansible/inventory/group_vars/all/inventory.yml`` file:
+add in the :file:`ansible/inventory/group_vars/all/inventory.yml` file:
 
 .. code-block:: yaml
 
@@ -57,4 +59,3 @@ contain the following code:
 
        - role: custom-role
          tags: [ 'role::custom' ]
-

docs/custom-features.rst

@@ -1,14 +1,16 @@
 Custom DebOps features
 ======================
 
+.. include:: includes/all.rst
+
 To make integration of DebOps roles with your own infrastructure easier, DebOps
 playbooks include a set of Ansible plugins and introduce several new concepts
 to Ansible best practices.
 
 The project directory
 ---------------------
 
-By default, Ansible is written to use ``/etc/ansible/`` directory and its
+By default, Ansible is written to use :file:`/etc/ansible/` directory and its
 contents in its daily use. In contrast to this, DebOps playbooks are designed
 to be used from a custom local directory, which you can initialize using
 ``debops-init`` command. By using Ansible this way, it's much easier to create
@@ -20,7 +22,7 @@ custom variables and so on.
 The official playbooks and roles are installed in central, fixed location
 (``~/.local/share/debops/debops-playbooks/`` on Linux systems), and the
 ``debops`` script generates ``ansible.cfg`` configuration file to provide
-correct paths for ``ansible-playbook`` command to use them indirectly from the
+correct paths for :command:`ansible-playbook` command to use them indirectly from the
 project directory.
 
 You can store your custom playbooks and roles in the project directory, in
@@ -34,11 +36,11 @@ contains tasks that are expected to be run on any and all hosts managed by
 Ansible.
 
 In DebOps, there is an entire playbook dedicated to this, located in
-``playbooks/common.yml``. It includes multiple roles that prepare a host from
-an unknown to a known state - for example, a ``ferm``-based firewall will be
+:file:`playbooks/common.yml`. It includes multiple roles that prepare a host from
+an unknown to a known state - for example, a :program:`ferm`-based firewall will be
 installed and configured on a given host, unless disabled, some common, useful
 packages will be installed, and so on. Other DebOps roles not included in the
-``common.yml`` playbook are designed for hosts that were configured by it
+:file:`common.yml` playbook are designed for hosts that were configured by it
 - they might work outside of that environment, but it's not guaranteed.
 
 Host group namespace
@@ -54,7 +56,7 @@ included in it, use ``[debops_all_hosts]`` group. This is a base group of the
 project and all hosts managed by DebOps should be included in it.
 
 Service playbooks use the ``[debops_service_*]`` group namespace in Ansible
-inventory (for example, ``debops.nginx`` role is activated on hosts in
+inventory (for example, debops.nginx_ role is activated on hosts in
 ``[debops_service_nginx]`` group). Some service playbooks use additional groups
 for various purposes; you are advised to check the role documentation to see
 what is their intended use case.
@@ -64,7 +66,7 @@ Flattened lists in inventory
 
 Some DebOps roles use sets of default variables (usually lists) to allow you to
 define different settings for all hosts in inventory, a group of hosts, or even
-specific hosts. For example, using ``debops.sshd`` role you can whitelist
+specific hosts. For example, using debops.sshd_ role you can whitelist
 a certain subnet for all hosts in your inventory, add another subnet for
 a particular group of hosts, and so on. You can also override more general
 list on specific hosts if needed.
@@ -89,12 +91,11 @@ your own tasks at the beginning or end of these roles, which gives you more
 control over the configuration.
 
 By combining above techniques, you can very easily extend DebOps roles without
-losing the ability to update them using ``git`` without merge conflicts.
+losing the ability to update them using :command:`git` without merge conflicts.
 
 LDAP integration
 ----------------
 
 Certain DebOps roles can access LDAP server to create or update data as needed.
 Custom modules are provided for LDAP entry and attribute management, deeper
 integration is planned in the future.
-

docs/guides/getting-started.rst

@@ -1,6 +1,8 @@
 Getting Started with DebOps
 ===========================
 
+.. include:: ../includes/all_from_subdir.rst
+
 Welcome to DebOps! You have installed Ansible and DebOps scripts, downloaded
 the roles and playbooks, and are wondering where to go next? Here you can read
 about creating your first DebOps project, and managing remote hosts.
@@ -25,7 +27,7 @@ configured. Everything else will be installed as needed.
    If you are using Debian Jessie or other distributions based on it as the
    base install, by default OpenSSH server configured by the installer will
    disallow password authentication on the ``root`` account. You can either
-   enable it manually in the ``/etc/ssh/sshd_config`` file, or configure
+   enable it manually in the :file:`/etc/ssh/sshd_config` file, or configure
    a separate admin account and use that to bootstrap the host.
 
 An important part of the environment is correctly configured DNS. Some of the
@@ -81,7 +83,7 @@ main project directory, so let's ``cd`` into it:
    alice@laptop:~$ cd ~/myproject
 
 Ansible uses a ``hosts`` file to identify hosts that are under its control. In
-the project directory this file is located in ``ansible/inventory/hosts``. Open
+the project directory this file is located in :command:`ansible/inventory/hosts`. Open
 it in your favorite text editor and add the remote host in the main DebOps
 host group:
 
@@ -104,13 +106,13 @@ variables which, when set correctly in inventory, can save you a trip to the
 data center.
 
 To make sure that these variables apply to all hosts in your environment, you
-can include them in ``ansible/inventory/group_vars/all/`` directory. A common
+can include them in :command:`ansible/inventory/group_vars/all/` directory. A common
 practice is to name the files inside inventory directories after variable
 prefixes, separately for each Ansible role. For example, variables related to
-``debops.sshd`` role are stored in
-``ansible/inventory/group_vars/all/sshd.yml``, variables used by the
-``debops.postfix`` role are written in
-``ansible/inventory/group_vars/all/postfix.yml``, and so on. The same scheme
+debops.sshd_ role are stored in
+:file:`ansible/inventory/group_vars/all/sshd.yml`, variables used by the
+debops.postfix_ role are written in
+:file:`ansible/inventory/group_vars/all/postfix.yml`, and so on. The same scheme
 can be used in other inventory groups or for separate hosts.
 
 ansible_ssh_user
@@ -150,7 +152,7 @@ bootstrap__domain
 
 If hosts that you want to manage don't have a DNS domain set, or it's incorrect
 (for example your VPS provider's domain instead of your own), the
-``debops.bootstrap`` role can be used to easily fix that and configure your own
+debops.bootstrap_ role can be used to easily fix that and configure your own
 domain. By setting this variable to, for example:
 
 .. code-block:: yaml
@@ -159,7 +161,7 @@ domain. By setting this variable to, for example:
    bootstrap__domain: 'example.com'
 
 By running the ``debops bootstrap`` command (see further down), your domain
-will be configured in the remote hosts' ``/etc/hosts`` file. Additionally, the
+will be configured in the remote hosts' :file:`/etc/hosts` file. Additionally, the
 hostname will be changed to the one you specified in the Ansible inventory.
 After that is done, it's best to reboot the machine to make sure all of the
 changed settings are applied and are persistent.
@@ -184,17 +186,17 @@ expected, but if you still are getting blocked, or to be sure that remote
 access won't be interrupted, you can define a list of IP addresses or CIDR
 subnets that will be allowed to connect to SSH without restrictions.
 
-To do that, in ``ansible/inventory/group_vars/all/sshd.yml`` add:
+To do that, in :file:`ansible/inventory/group_vars/all/sshd.yml` add:
 
 .. code-block:: yaml
 
    ---
    sshd__whitelist: [ '192.0.2.0/24', '2001:db8::/32' ]
 
-This will configure the ``debops.ferm`` and ``debops.tcpwrappers`` roles
-to allow connections to the ``ssh`` service from specified networks.
+This will configure the debops.ferm_ and debops.tcpwrappers_ roles
+to allow connections to the :command:`ssh` service from specified networks.
 
-The ``debops.sshd`` role has `many more variables <http://docs.debops.org/en/latest/ansible/roles/ansible-sshd/docs/defaults.html>`_, you can checkout to see the default configuration used by DebOps and what can be changed as needed.
+The debops.sshd_ role has `many more variables <http://docs.debops.org/en/latest/ansible/roles/ansible-sshd/docs/defaults.html>`_, you can checkout to see the default configuration used by DebOps and what can be changed as needed.
 
 ntp__timezone
 ~~~~~~~~~~~~~
@@ -247,7 +249,7 @@ without issues.
 The Raspbian operating system is a little difficult to detect, because Ansible
 currently classifies it as "Debian", however its package repositories are
 completely different. To avoid issues with incompatible package sources on your
-Raspberry Pi/Pi2, you should change the default ``debops.apt`` configuration
+Raspberry Pi/Pi2, you should change the default debops.apt_ configuration
 manually to use the Raspbian repositories. To do that, add these values in
 relevant inventory files:
 
@@ -281,18 +283,17 @@ Or, for short:
 
    alice@laptop:~/myproject$ debops bootstrap -l server -u root -k
 
-This command will execute the `debops.bootstrap
-<http://docs.debops.org/en/latest/ansible/roles/ansible-bootstrap/docs/index.html>`_
+This command will execute the debops.bootstrap_
 role and use it to install a base set of packages needed by Ansible like
-``python`` and ``sudo``, prepare a new administrator account named after your
+``python`` and :command:`sudo`, prepare a new administrator account named after your
 system user (``alice`` in our example) and allow that account full access to
-the ``root`` account using ``sudo``. Your SSH keys will be installed on both
+the ``root`` account using :command:`sudo`. Your SSH keys will be installed on both
 the ``root`` and administrator accounts.
 
 .. note::
 
    Bootstrapping a host this way is not needed if you already have an
-   administrator account that can use ``sudo`` without a password. This
+   administrator account that can use :command:`sudo` without a password. This
    includes hosts configured using Debian Preseed provided by DebOps as well as
    OpenVZ/LXC containers configured using provided templates.
 
@@ -304,7 +305,7 @@ password:
 
    alice@laptop:~/myproject$ ssh server
 
-After logging in, check if you can run commands using ``sudo`` without
+After logging in, check if you can run commands using :command:`sudo` without
 a password:
 
 .. code-block:: console
@@ -321,7 +322,7 @@ the configuration:
 
    alice@laptop:~/myproject$ debops -l server
 
-This will start the ``ansible-playbook`` command with the main DebOps playbook. This by default includes the `common playbook <https://github.com/debops/debops-playbooks/blob/master/playbooks/common.yml>`_ with a default set of roles, and any additional playbooks, if they have been enabled.
+This will start the :command:`ansible-playbook` command with the main DebOps playbook. This by default includes the `common playbook <https://github.com/debops/debops-playbooks/blob/master/playbooks/common.yml>`_ with a default set of roles, and any additional playbooks, if they have been enabled.
 
 The initial configuration might take 5-10 minutes on a reasonably fast machine.
 There are some steps, like Diffie-Hellman parameter generation, which might
@@ -335,7 +336,7 @@ with:
   to your admin account;
 - a set of Diffie-Hellman parameters and SSL certificates ready to use by
   different services (encrypted TLS/SSL connections out of the box);
-- configured ``iptables``/``ip6tables`` firewall and TCP Wrappers;
+- configured :command:`iptables`/:command:`ip6tables` firewall and TCP Wrappers;
 - enabled network time synchronization as needed;
 - a set of useful management software installed on the host (``htop``,
   ``mtr-tiny``, ``mc``, ``vim``, among other things);
@@ -348,10 +349,10 @@ services. After a host is configured, you can enable additional Ansible roles
 to install and configure software and applications of your choice.
 
 We will use `DokuWiki <http://dokuwiki.org/>`_ as an example application. The
-role that manages the installation is called ``debops.dokuwiki``, it uses
-``debops.nginx`` and ``debops.php5`` roles to configure a webserver and PHP5
-environment. The ``debops.nginx`` role calls some additional roles, such as
-``debops.ferm`` to configure needed services.
+role that manages the installation is called debops.dokuwiki_, it uses
+debops.nginx_ and debops.php5_ roles to configure a webserver and PHP5
+environment. The debops.nginx_ role calls some additional roles, such as
+debops.ferm_ to configure needed services.
 
 To install DokuWiki on your new remote host, you need to enable the respective
 role in Ansible inventory. This is done by creating a new host group,
@@ -369,14 +370,14 @@ hosts to it:
 As you can see, you don't need to copy the whole host entry, only the short
 name is enough.
 
-The ``debops.dokuwiki`` has `many default variables
+The debops.dokuwiki_ has `many default variables
 <http://docs.debops.org/en/latest/ansible/roles/ansible-dokuwiki/docs/defaults.html>`_
 you can use to customize the installation. One of the more useful ones is
 ``dokuwiki_main_domain``; it's a list which specifies what DNS subdomains are
 used to access the wiki (each application in the DebOps set of roles is
 configured on a separate subdomain). By default DokuWiki will be accessible on
 the ``wiki.{{ ansible_domain }}`` subdomain, if you want to change it, you can
-do so by creating the ``ansible/inventory/host_vars/server/dokuwiki.yml``
+do so by creating the :file:`ansible/inventory/host_vars/server/dokuwiki.yml`
 configuration file and specifying the subdomain(s) in it:
 
 .. code-block:: yaml
@@ -405,17 +406,17 @@ as the first argument to the ``debops`` command:
 
 This will tell the script to look for the playbook in several places:
 
-- ``playbooks/`` and ``ansible/playbooks/`` subdirectories in the project
+- ``playbooks/`` and :command:`ansible/playbooks/` subdirectories in the project
   directory;
 - ``debops-playbooks/playbooks/`` subdirectory of the project directory, if
   DebOps playbooks and roles are installed inside of it;
 - ``~/.local/share/debops/debops-playbooks/playbooks/`` directory (default
   install location);
 
 The first one found will be executed. You can use this to your advantage by
-adding custom playbooks in ``playbooks/`` or ``ansible/playbooks/``
+adding custom playbooks in ``playbooks/`` or :command:`ansible/playbooks/`
 directories, they need the be named with ``.yml`` extension. Custom roles can
-be placed in the ``roles/`` or ``ansible/roles/`` subdirectories located in the
+be placed in the ``roles/`` or :command:`ansible/roles/` subdirectories located in the
 project directory.
 
 After Ansible finishes the configuration, you will need to go to the
@@ -425,7 +426,7 @@ process.
 At this time you might find that the web browser you are using does not
 recognize the CA certificates served by the host. This happens when server uses
 certificates signed by internal DebOps Certificate Authority instead of the
-"regular" ones. To fix that, consult the ``debops.pki`` role documentation
+"regular" ones. To fix that, consult the debops.pki_ role documentation
 (when it's available).
 
 Where to go from here

docs/guides/linux-containers.rst

@@ -30,7 +30,7 @@ Configuring a host
 
 The paths are relative to where you ``debops-init`` a new project.
 
-``ansible/inventory/hosts``
+:command:`ansible/inventory/hosts`
 
 ::
 
@@ -45,7 +45,7 @@ dnsmasq.
 
 Basically this means you don't have to forward ports and DNS will work.
 
-``ansible/inventory/host_vars/yourhostname.yml``
+:file:`ansible/inventory/host_vars/yourhostname.yml`
 
 ::
 
@@ -100,14 +100,14 @@ this point you have a bare container ready to do whatever you want.
 If you plan to use containers for development then you'll probably want
 to group your containers together in your inventory.
 
-``ansible/inventory/hosts``
+:command:`ansible/inventory/hosts`
 
 ::
 
     [local_containers]
     mycontainer
 
-Now you could create ``ansible/inventory/group_vars/local_containers.yml`` and
+Now you could create :file:`ansible/inventory/group_vars/local_containers.yml` and
 start doing things that would apply to all local containers.
 
 Perhaps you want to install emacs or use your own dotfiles, etc..
@@ -129,6 +129,6 @@ To transfer files to/from the container you have 2 options.
 The second option requires knowing the dirty details about where the container
 has its configuration and file system stored.
 
-On the LXC host, navigate to ``/var/lib/lxc``, then go into your container's
+On the LXC host, navigate to :file:`/var/lib/lxc`, then go into your container's
 directory. You can find its file system there among other things. You can simply
 ``cp`` directly if your LXC host is local to your main OS.

docs/guides/local-apt-repository.rst

@@ -23,7 +23,7 @@ seconds once you setup your local APT server once.
 
 It also future proofs your role because you wouldn't have to change anything
 once the next Debian version is officially released. From the role's point of view it's just
-installing an apt package using Ansible's ``apt`` module. It does not care where
+installing an apt package using Ansible's :command:`apt` module. It does not care where
 the apt server is located.
 
 Pick a server

docs/guides/service-ports.rst

@@ -2,7 +2,7 @@ Custom services and their default ports
 =======================================
 
 In various DebOps roles you can find named ports. They are defined in
-``/etc/services`` using `debops.etc_services`_ role which manages them using
+:file:`/etc/services` using `debops.etc_services`_ role which manages them using
 Ansible's ``assemble`` module. To avoid collisions between various services we
 list here custom ports that are set for applications and services that don't
 have specified system ports by default.

docs/includes/all.rst

@@ -0,0 +1 @@
+.. include:: includes/global.rst

docs/includes/all_from_subdir.rst

@@ -0,0 +1,2 @@
+.. include:: ../includes/global.rst
+.. Refer to: https://github.com/debops/docs/issues/155#issuecomment-233184276