docs: fix some markup issues and typos

docs/conf.py

@@ -20,7 +20,7 @@ release = '1.4.8'
 
 pygments_style = 'sphinx'
 
-# External links to the bug tracker.
+# External links to the bug tracker and other sites.
 extlinks = {
     'bug': ('https://github.com/beetbox/beets/issues/%s', '#'),
     'user': ('https://github.com/%s', ''),

docs/plugins/absubmit.rst

@@ -1,15 +1,15 @@
 AcousticBrainz Submit Plugin
 ============================
 
-The `absubmit` plugin lets you submit acoustic analysis results to the
+The ``absubmit`` plugin lets you submit acoustic analysis results to the
 `AcousticBrainz`_ server.
 
 Installation
 ------------
 
-The `absubmit` plugin requires the `streaming_extractor_music`_ program to run. Its source can be found on `GitHub`_, and while it is possible to compile the extractor from source, AcousticBrainz would prefer if you used their binary (see the AcousticBrainz `FAQ`_).
+The ``absubmit`` plugin requires the `streaming_extractor_music`_ program to run. Its source can be found on `GitHub`_, and while it is possible to compile the extractor from source, AcousticBrainz would prefer if you used their binary (see the AcousticBrainz `FAQ`_).
 
-The `absubmit` also plugin requires `requests`_, which you can install using `pip`_ by typing::
+The ``absubmit`` plugin also requires `requests`_, which you can install using `pip`_ by typing::
 
     pip install requests
 

docs/plugins/badfiles.rst

@@ -48,11 +48,11 @@ Here is an example where the FLAC decoder signals a corrupt file::
       00.flac: ERROR while decoding data
                  state = FLAC__STREAM_DECODER_READ_FRAME
 
-Note that the default `mp3val` checker is a bit verbose and can output a lot
+Note that the default ``mp3val`` checker is a bit verbose and can output a lot
 of "stream error" messages, even for files that play perfectly well.
 Generally, if more than one stream error happens, or if a stream error happens
 in the middle of a file, this is a bad sign.
 
 By default, only errors for the bad files will be shown. In order for the
-results for all of the checked files to be seen, including the uncorrupted 
+results for all of the checked files to be seen, including the uncorrupted
 ones, use the ``-v`` or ``--verbose`` option.

docs/plugins/bpd.rst

@@ -20,7 +20,7 @@ with its Python bindings) on your system.
   gst-plugins-base pygobject3``.
 
 * On Linux, you need to install GStreamer 1.0 and the GObject bindings for
-  python. Under Ubuntu, they are called `python-gi` and `gstreamer1.0`.
+  python. Under Ubuntu, they are called ``python-gi`` and ``gstreamer1.0``.
 
 * On Windows, you may want to try `GStreamer WinBuilds`_ (caveat emptor: I
   haven't tried this).

docs/plugins/bucket.rst

@@ -27,19 +27,19 @@ The ``bucket_year`` parameter is used for all substitutions occurring on the
 The definition of a range is somewhat loose, and multiple formats are allowed:
 
 - For alpha ranges: the range is defined by the lowest and highest (ASCII-wise)
-  alphanumeric characters in the string you provide. For example, *ABCD*,
-  *A-D*, *A->D*, and *[AD]* are all equivalent.
+  alphanumeric characters in the string you provide. For example, ``ABCD``,
+  ``A-D``, ``A->D``, and ``[AD]`` are all equivalent.
 - For year ranges: digits characters are extracted and the two extreme years
-  define the range. For example, *1975-77*, *1975,76,77* and *1975-1977* are
+  define the range. For example, ``1975-77``, ``1975,76,77`` and ``1975-1977`` are
   equivalent. If no upper bound is given, the range is extended to current year
-  (unless a later range is defined). For example, *1975* encompasses all years
+  (unless a later range is defined). For example, ``1975`` encompasses all years
   from 1975 until now.
 
-The `%bucket` template function guesses whether to use alpha- or year-style
+The ``%bucket`` template function guesses whether to use alpha- or year-style
 buckets depending on the text it receives. It can guess wrong if, for example,
-an artist or album happens to begin with four digits. Provide `alpha` as the
+an artist or album happens to begin with four digits. Provide ``alpha`` as the
 second argument to the template to avoid this automatic detection: for
-example, use `%bucket{$artist,alpha}`.
+example, use ``%bucket{$artist,alpha}``.
 
 
 Configuration
@@ -56,7 +56,7 @@ The available options are:
   overrides original range definition.
   Default: none.
 - **bucket_year**: Ranges to use for all substitutions occurring on the
-  `$year` field.
+  ``$year`` field.
   Default: none.
 - **extrapolate**: Enable this if you want to group your files into multiple
   year ranges without enumerating them all. This option will generate year
@@ -73,5 +73,5 @@ Here's an example::
            'A - D': ^[0-9a-dA-D…äÄ]
 
 This configuration creates five-year ranges for any input year.
-The *A - D* bucket now matches also all artists starting with ä or Ä and 0 to 9
+The `A - D` bucket now matches also all artists starting with ä or Ä and 0 to 9
 and … (ellipsis). The other alpha buckets work as ranges.

docs/plugins/convert.rst

@@ -122,7 +122,7 @@ and select a command with the ``--format`` command-line option or the
 
 In this example ``beet convert`` will use the *speex* command by
 default. To convert the audio to `wav`, run ``beet convert -f wav``.
-This will also use the format key (`wav`) as the file extension.
+This will also use the format key (``wav``) as the file extension.
 
 Each entry in the ``formats`` map consists of a key (the name of the
 format) as well as the command and optionally the file extension.

docs/plugins/embyupdate.rst

@@ -34,5 +34,5 @@ The available options under the ``emby:`` section are:
 - **password**: The password for the user. (This is only necessary if no API
   key is provided.)
 
-You can choose to authenticate either with `apikey` or `password`, but only
+You can choose to authenticate either with ``apikey`` or ``password``, but only
 one of those two is required.

docs/plugins/export.rst

@@ -42,7 +42,7 @@ Configuration
 To configure the plugin, make a ``export:`` section in your configuration
 file. Under the ``json`` key, these options are available:
 
-- **ensure_ascii**: Escape non-ASCII characters with `\uXXXX` entities.
+- **ensure_ascii**: Escape non-ASCII characters with ``\uXXXX`` entities.
 
 - **indent**: The number of spaces for indentation.
 

docs/plugins/fetchart.rst

@@ -73,18 +73,18 @@ or `Pillow`_.
 
 .. note::
 
-    Previously, there was a `remote_priority` option to specify when to
+    Previously, there was a ``remote_priority`` option to specify when to
     look for art on the filesystem. This is
     still respected, but a deprecation message will be shown until you
-    replace this configuration with the new `filesystem` value in the
-    `sources` array.
+    replace this configuration with the new ``filesystem`` value in the
+    ``sources`` array.
 
 .. _beets custom search engine: https://cse.google.com.au:443/cse/publicurl?cx=001442825323518660753:hrh5ch1gjzm
 .. _Pillow: https://github.com/python-pillow/Pillow
 .. _ImageMagick: http://www.imagemagick.org/
 
-Here's an example that makes plugin select only images that contain *front* or
-*back* keywords in their filenames and prioritizes the iTunes source over
+Here's an example that makes plugin select only images that contain ``front`` or
+``back`` keywords in their filenames and prioritizes the iTunes source over
 others::
 
     fetchart:

docs/plugins/freedesktop.rst

@@ -3,4 +3,4 @@ Freedesktop Plugin
 
 The ``freedesktop`` plugin created .directory files in your album folders.
 This plugin is now deprecated and replaced by the :doc:`/plugins/thumbnails`
-with the `dolphin` option enabled.
+with the ``dolphin`` option enabled.

docs/plugins/gmusic.rst

@@ -8,7 +8,7 @@ songs in your library.
 Installation
 ------------
 
-The plugin requires `gmusicapi`_. You can install it using `pip`::
+The plugin requires :pypi:`gmusicapi`. You can install it using ``pip``::
 
     pip install gmusicapi
 

docs/plugins/index.rst

@@ -13,11 +13,11 @@ Using Plugins
 -------------
 
 To use one of the plugins included with beets (see the rest of this page for a
-list), just use the `plugins` option in your :doc:`config.yaml </reference/config>` file, like so::
+list), just use the ``plugins`` option in your :doc:`config.yaml </reference/config>` file, like so::
 
     plugins: inline convert web
 
-The value for `plugins` can be a space-separated list of plugin names or a
+The value for ``plugins`` can be a space-separated list of plugin names or a
 YAML list like ``[foo, bar]``. You can see which plugins are currently enabled
 by typing ``beet version``.
 
@@ -30,7 +30,7 @@ Each plugin has its own set of options that can be defined in a section bearing
 
 Some plugins have special dependencies that you'll need to install. The
 documentation page for each plugin will list them in the setup instructions.
-For some, you can use `pip`'s "extras" feature to install the dependencies,
+For some, you can use ``pip``'s "extras" feature to install the dependencies,
 like this::
 
     pip install beets[fetchart,lyrics,lastgenre]
@@ -213,14 +213,14 @@ In addition to the plugins that come with beets, there are several plugins
 that are maintained by the beets community. To use an external plugin, there
 are two options for installation:
 
-* Make sure it's in the Python path (known as `sys.path` to developers). This
+* Make sure it's in the Python path (known as ``sys.path`` to developers). This
   just means the plugin has to be installed on your system (e.g., with a
-  `setup.py` script or a command like `pip` or `easy_install`).
+  ``setup.py`` script or a command like ``pip`` or ``easy_install``).
 
-* Set the `pluginpath` config variable to point to the directory containing the
+* Set the ``pluginpath`` config variable to point to the directory containing the
   plugin. (See :doc:`/reference/config`.)
 
-Once the plugin is installed, enable it by placing its name on the `plugins`
+Once the plugin is installed, enable it by placing its name on the ``plugins``
 line in your config file.
 
 Here are a few of the plugins written by the beets community:

docs/plugins/lyrics.rst

@@ -60,9 +60,9 @@ configuration file. The available options are:
 - **sources**: List of sources to search for lyrics. An asterisk ``*`` expands
   to all available sources.
   Default: ``google lyricwiki musixmatch genius``, i.e., all the
-  available sources. The `google` source will be automatically
+  available sources. The ``google`` source will be automatically
   deactivated if no ``google_API_key`` is setup.
-  Both it and the `genius` source will only be enabled if BeautifulSoup is
+  Both it and the ``genius`` source will only be enabled if BeautifulSoup is
   installed.
 
 Here's an example of ``config.yaml``::

docs/plugins/mbsync.rst

@@ -30,7 +30,7 @@ The command has a few command-line options:
 * By default, files will be moved (renamed) according to their metadata if
   they are inside your beets library directory. To disable this, use the
   ``-M`` (``--nomove``) command-line option.
-* If you have the `import.write` configuration option enabled, then this
+* If you have the ``import.write`` configuration option enabled, then this
   plugin will write new metadata to files' tags. To disable this, use the
   ``-W`` (``--nowrite``) option.
 * To customize the output of unrecognized items, use the ``-f``

docs/plugins/play.rst

@@ -32,8 +32,8 @@ command-line oriented, and you'll get its output in real time.
 Interactive Usage
 -----------------
 
-The `play` plugin can also be invoked during an import. If enabled, the plugin
-adds a `plaY` option to the prompt, so pressing `y` will execute the configured
+The ``play`` plugin can also be invoked during an import. If enabled, the plugin
+adds a ``plaY`` option to the prompt, so pressing ``y`` will execute the configured
 command and play the items currently being imported.
 
 Once the configured command exits, you will be returned to the import

docs/plugins/replaygain.rst

@@ -24,9 +24,9 @@ GStreamer
 
 To use `GStreamer`_ for ReplayGain analysis, you will of course need to
 install GStreamer and plugins for compatibility with your audio files.
-You will need at least GStreamer 1.0 and `PyGObject 3.x`_ (a.k.a. python-gi).
+You will need at least GStreamer 1.0 and `PyGObject 3.x`_ (a.k.a. ``python-gi``).
 
-.. _PyGObject 3.x: https://wiki.gnome.org/action/show/Projects/PyGObject
+.. _PyGObject 3.x: https://pygobject.readthedocs.io/en/latest/
 .. _GStreamer: http://gstreamer.freedesktop.org/
 
 Then, enable the ``replaygain`` plugin (see :ref:`using-plugins`) and specify

docs/plugins/smartplaylist.rst

@@ -36,7 +36,7 @@ For more advanced usage, you can use template syntax (see
       query: 'year::201(0|1)'
 
 This will query all the songs in 2010 and 2011 and generate the two playlist
-files `ReleasedIn2010.m3u` and `ReleasedIn2011.m3u` using those songs.
+files ``ReleasedIn2010.m3u`` and ``ReleasedIn2011.m3u`` using those songs.
 
 You can also gather the results of several queries by putting them in a list.
 (Items that match both queries are not included twice.) For example::

docs/plugins/thumbnails.rst

@@ -7,7 +7,7 @@ Nautilus or Thunar, and is therefore POSIX-only.
 
 To use the ``thumbnails`` plugin, enable it (see :doc:`/plugins/index`) as well
 as the :doc:`/plugins/fetchart`.  You'll need 2 additional python packages:
-`pyxdg` and `pathlib`.
+:pypi:`pyxdg` and :pypi:`pathlib`.
 
 ``thumbnails`` needs to resize the covers, and therefore requires either
 `ImageMagick`_ or `Pillow`_.