From 2e0230789f86a44adf04cad830224c208ca41a9f Mon Sep 17 00:00:00 2001 From: Carl Suster Date: Sat, 27 Apr 2019 12:43:13 +1000 Subject: [PATCH] docs: fix some markup issues and typos --- docs/conf.py | 2 +- docs/plugins/absubmit.rst | 6 +++--- docs/plugins/badfiles.rst | 4 ++-- docs/plugins/bpd.rst | 2 +- docs/plugins/bucket.rst | 18 +++++++++--------- docs/plugins/convert.rst | 2 +- docs/plugins/embyupdate.rst | 2 +- docs/plugins/export.rst | 2 +- docs/plugins/fetchart.rst | 10 +++++----- docs/plugins/freedesktop.rst | 2 +- docs/plugins/gmusic.rst | 2 +- docs/plugins/index.rst | 14 +++++++------- docs/plugins/lyrics.rst | 4 ++-- docs/plugins/mbsync.rst | 2 +- docs/plugins/play.rst | 4 ++-- docs/plugins/replaygain.rst | 4 ++-- docs/plugins/smartplaylist.rst | 2 +- docs/plugins/thumbnails.rst | 2 +- 18 files changed, 42 insertions(+), 42 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index e9dcd0342..7e52d283e 100644 --- a/docs/conf.py +++ b/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', ''), diff --git a/docs/plugins/absubmit.rst b/docs/plugins/absubmit.rst index feebc1642..30a77d4b0 100644 --- a/docs/plugins/absubmit.rst +++ b/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 diff --git a/docs/plugins/badfiles.rst b/docs/plugins/badfiles.rst index 0a32f1a36..a59dbd0d1 100644 --- a/docs/plugins/badfiles.rst +++ b/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. diff --git a/docs/plugins/bpd.rst b/docs/plugins/bpd.rst index ee36c040c..87c931793 100644 --- a/docs/plugins/bpd.rst +++ b/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). diff --git a/docs/plugins/bucket.rst b/docs/plugins/bucket.rst index 99975968f..ee1857777 100644 --- a/docs/plugins/bucket.rst +++ b/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. diff --git a/docs/plugins/convert.rst b/docs/plugins/convert.rst index 1a487cdee..92545af30 100644 --- a/docs/plugins/convert.rst +++ b/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. diff --git a/docs/plugins/embyupdate.rst b/docs/plugins/embyupdate.rst index 00373b98c..d820f5c6b 100644 --- a/docs/plugins/embyupdate.rst +++ b/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. diff --git a/docs/plugins/export.rst b/docs/plugins/export.rst index 4192f00c5..4326ccb16 100644 --- a/docs/plugins/export.rst +++ b/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. diff --git a/docs/plugins/fetchart.rst b/docs/plugins/fetchart.rst index 002471ec1..8af7f686a 100644 --- a/docs/plugins/fetchart.rst +++ b/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: diff --git a/docs/plugins/freedesktop.rst b/docs/plugins/freedesktop.rst index 61943718e..0368cc5da 100644 --- a/docs/plugins/freedesktop.rst +++ b/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. diff --git a/docs/plugins/gmusic.rst b/docs/plugins/gmusic.rst index a4f4c8e05..94ee2dae4 100644 --- a/docs/plugins/gmusic.rst +++ b/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 diff --git a/docs/plugins/index.rst b/docs/plugins/index.rst index e885db39b..e75e2f810 100644 --- a/docs/plugins/index.rst +++ b/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 ` file, like so:: +list), just use the ``plugins`` option in your :doc:`config.yaml ` 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: diff --git a/docs/plugins/lyrics.rst b/docs/plugins/lyrics.rst index 4131c85d9..799bd0325 100644 --- a/docs/plugins/lyrics.rst +++ b/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``:: diff --git a/docs/plugins/mbsync.rst b/docs/plugins/mbsync.rst index a7633a500..1c8663dca 100644 --- a/docs/plugins/mbsync.rst +++ b/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`` diff --git a/docs/plugins/play.rst b/docs/plugins/play.rst index 86920c9ac..d72ec4e0d 100644 --- a/docs/plugins/play.rst +++ b/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 diff --git a/docs/plugins/replaygain.rst b/docs/plugins/replaygain.rst index ad0e50e22..825f279e2 100644 --- a/docs/plugins/replaygain.rst +++ b/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 diff --git a/docs/plugins/smartplaylist.rst b/docs/plugins/smartplaylist.rst index 2f691c4fe..8ccbd0091 100644 --- a/docs/plugins/smartplaylist.rst +++ b/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:: diff --git a/docs/plugins/thumbnails.rst b/docs/plugins/thumbnails.rst index 5753a9f7e..c2a28d091 100644 --- a/docs/plugins/thumbnails.rst +++ b/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`_.