From e6725b697383cb0bb476498f1db6b2ca01a90903 Mon Sep 17 00:00:00 2001 From: Adrian Sampson Date: Tue, 24 Sep 2013 20:33:46 -0700 Subject: [PATCH] docs: reorg plugins section; add dev section --HG-- rename : docs/plugins/writing.rst => docs/dev/plugins.rst --- docs/dev/api.rst | 4 + docs/dev/index.rst | 10 +++ docs/{plugins/writing.rst => dev/plugins.rst} | 0 docs/guides/advanced.rst | 4 +- docs/guides/main.rst | 2 +- docs/index.rst | 3 +- docs/plugins/index.rst | 79 +++++++------------ 7 files changed, 48 insertions(+), 54 deletions(-) create mode 100644 docs/dev/api.rst create mode 100644 docs/dev/index.rst rename docs/{plugins/writing.rst => dev/plugins.rst} (100%) diff --git a/docs/dev/api.rst b/docs/dev/api.rst new file mode 100644 index 000000000..7747cbb67 --- /dev/null +++ b/docs/dev/api.rst @@ -0,0 +1,4 @@ +API Documentation +================= + +TK. diff --git a/docs/dev/index.rst b/docs/dev/index.rst new file mode 100644 index 000000000..2579ecbf4 --- /dev/null +++ b/docs/dev/index.rst @@ -0,0 +1,10 @@ +For Developers +============== + +This section contains information for developers. Read on if you're interested +in hacking beets itself or creating plugins for it. + +.. toctree:: + + plugins + api diff --git a/docs/plugins/writing.rst b/docs/dev/plugins.rst similarity index 100% rename from docs/plugins/writing.rst rename to docs/dev/plugins.rst diff --git a/docs/guides/advanced.rst b/docs/guides/advanced.rst index fec105e4d..c7baad5e8 100644 --- a/docs/guides/advanced.rst +++ b/docs/guides/advanced.rst @@ -20,7 +20,7 @@ comes from MusicBrainz. Plugins can provide :doc:`album art If you want beets to get any of this data automatically during the import process, just enable any of the three relevant plugins (see -:ref:`using-plugins`). For example, put this line in your :doc:`config file +:doc:`/plugins/index`). For example, put this line in your :doc:`config file ` to enable all three:: plugins: fetchart lyrics lastgenre @@ -67,7 +67,7 @@ but play it at work (without copying my whole library locally). The :doc:`/plugins/web` makes streaming your music easy---it's sort of like having your own personal Spotify. -First, enable the ``web`` plugin (see :ref:`using-plugins`). Run the server by +First, enable the ``web`` plugin (see :doc:`/plugins/index`). Run the server by typing ``beet web`` and head to http://localhost:8337 in a browser. You can browse your collection with queries and, if your browser supports it, play music using HTML5 audio. diff --git a/docs/guides/main.rst b/docs/guides/main.rst index 8fa9e9b76..80d1abf4f 100644 --- a/docs/guides/main.rst +++ b/docs/guides/main.rst @@ -238,7 +238,7 @@ is possible. You'll also want to glance over the :doc:`/reference/cli` page for a more detailed description of all of beets' functionality. (Like deleting music! That's important.) -Also, check out :ref:`included-plugins` as well as :ref:`other-plugins`. The +Also, check out :doc:`beets' plugins `. The real power of beets is in its extensibility---with plugins, beets can do almost anything for your music collection. diff --git a/docs/index.rst b/docs/index.rst index 81fc0d5b8..d5c5833f9 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -10,7 +10,7 @@ to build your music library. Then you can get a more detailed look at beets' features in the :doc:`/reference/cli/` and :doc:`/reference/config` references. You might also -be interested in exploring the :ref:`included-plugins`. +be interested in exploring the :doc:`plugins `. If you still need help, your can drop by the ``#beets`` IRC channel on Freenode, `email the author`_, or `file a bug`_ in the issue tracker. Please let me know @@ -30,6 +30,7 @@ Contents reference/index plugins/index faq + dev/index .. toctree:: :maxdepth: 1 diff --git a/docs/plugins/index.rst b/docs/plugins/index.rst index 451667639..dd0c6ee43 100644 --- a/docs/plugins/index.rst +++ b/docs/plugins/index.rst @@ -1,40 +1,20 @@ Plugins ======= -Plugins can extend beets' core functionality. Plugins can add new commands to -the command-line interface, respond to events in beets, augment the autotagger, -or provide new path template functions. +Plugins extend beets' core functionality. They add new commands, fetch +additional data during import, provide new metadata sources, and much more. If +beets by itself doesn't do what you want it to, you may just need to enable a +plugin---or, if you want to do something new, :doc:`writing a plugin +` is easy if you know a little Python. -.. _using-plugins: - -Using Plugins -------------- - -To use a plugin, you have two options: - -* 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`). - -* Set the `pluginpath` config variable to point to the directory containing the - plugin. (See :doc:`/reference/config`.) - -Then, set the `plugins` option in your `config.yaml` file, like so:: +To use one of the plugins included with beets (see below for a list), just use +the `plugins` option in your `config.yaml` file, like so:: plugins: mygreatplugin someotherplugin -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``. - -.. _included-plugins: - -Plugins Included With Beets ---------------------------- - -There are a few plugins that are included with the beets distribution. They're -disabled by default, but you can turn them on as described above. +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``. .. toctree:: :hidden: @@ -71,7 +51,7 @@ disabled by default, but you can turn them on as described above. ftintitle Autotagger Extensions -'''''''''''''''''''''' +--------------------- * :doc:`chroma`: Use acoustic fingerprinting to identify audio files with missing or incorrect metadata. @@ -84,7 +64,7 @@ Autotagger Extensions .. _Discogs: http://www.discogs.com/ Metadata -'''''''' +-------- * :doc:`lyrics`: Automatically fetch song lyrics. * :doc:`echonest_tempo`: Automatically fetch song tempos (bpm). @@ -99,7 +79,7 @@ Metadata field. Path Formats -'''''''''''' +------------ * :doc:`inline`: Use Python snippets to customize path format strings. * :doc:`rewrite`: Substitute values in path formats. @@ -107,7 +87,7 @@ Path Formats end). Interoperability -'''''''''''''''' +---------------- * :doc:`mpdupdate`: Automatically notifies `MPD`_ whenever the beets library changes. @@ -115,7 +95,7 @@ Interoperability * :doc:`smartplaylist`: Generate smart playlists based on beets queries. Miscellaneous -''''''''''''' +------------- * :doc:`web`: An experimental Web-based GUI for beets. * :doc:`random`: Randomly choose albums and tracks from your library. @@ -138,6 +118,20 @@ Miscellaneous Other Plugins ------------- +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 + 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`). + +* 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` +line in your config file. + Here are a few of the plugins written by the beets community: * `beetFs`_ is a FUSE filesystem for browsing the music in your beets library. @@ -145,24 +139,9 @@ Here are a few of the plugins written by the beets community: * `A cmus plugin`_ integrates with the `cmus`_ console music player. -* `featInTitle`_ moves featured artists from the artist tag to the title tag. - .. _beetFs: http://code.google.com/p/beetfs/ .. _Beet-MusicBrainz-Collection: https://github.com/jeffayle/Beet-MusicBrainz-Collection/ .. _A cmus plugin: https://github.com/coolkehon/beets/blob/master/beetsplug/cmus.py .. _cmus: http://cmus.sourceforge.net/ -.. _featInTitle: https://github.com/Verrus/beets-plugin-featInTitle/ - -Writing Plugins ---------------- - -If you know a little Python, you can write your own plugin to do almost anything -you can imagine with your music collection. See the :doc:`guide to writing beets -plugins `. - -.. toctree:: - :hidden: - - writing