diff --git a/beetsplug/lyrics.py b/beetsplug/lyrics.py index a1af67363..29bab25a6 100644 --- a/beetsplug/lyrics.py +++ b/beetsplug/lyrics.py @@ -690,6 +690,8 @@ class LyricsPlugin(plugins.BeetsPlugin): # The "write to files" option corresponds to the # import_write config value. write = ui.should_write() + if opts.writerst: + self.writerst_indexes(opts.writerst) for item in lib.items(ui.decargs(args)): if not opts.local_only and not self.config['local']: self.fetch_item_lyrics( @@ -704,6 +706,13 @@ class LyricsPlugin(plugins.BeetsPlugin): if opts.writerst: # flush last artist self.writerst(opts.writerst, None) + ui.print_(u'RST files generated. to build, use one of:') + ui.print_(u' sphinx-build -b html %s _build/html' + % opts.writerst) + ui.print_(u' sphinx-build -b epub %s _build/epub' + % opts.writerst) + ui.print_(u' sphinx-build -b latex %s _build/latex && make -C _build/latex all-pdf' + % opts.writerst) cmd.func = func return [cmd] @@ -737,6 +746,57 @@ class LyricsPlugin(plugins.BeetsPlugin): u'~' * len(title_str), block) + def writerst_indexes(self, directory): + """Write conf.py and index.rst files necessary for Sphinx + + We write minimal configurations that are necessary for Sphinx + to operate. We do not overwrite existing files so that + customizations are respected.""" + try: + os.makedirs(os.path.join(directory, 'artists')) + except OSError as e: + if e.errno == errno.EEXIST: + pass + else: + raise + indexfile = os.path.join(directory, 'index.rst') + if not os.path.exists(indexfile): + with open(indexfile, 'w') as output: + output.write(u'''Lyrics +====== + +* :ref:`Song index ` +* :ref:`search` + +Artist index: + +.. toctree:: + :maxdepth: 1 + :glob: + + artists/* +''') + conffile = os.path.join(directory, 'conf.py') + if not os.path.exists(conffile): + with open(conffile, 'w') as output: + output.write(u'''# -*- coding: utf-8 -*- +master_doc = 'index' +project = u'Lyrics' +copyright = u'none' +author = u'Various Authors' +latex_documents = [ + (master_doc, 'Lyrics.tex', project, + author, 'manual'), +] +epub_title = project +epub_author = author +epub_publisher = author +epub_copyright = copyright +epub_exclude_files = ['search.html'] +epub_tocdepth = 1 +epub_tocdup = False +''') + def imported(self, session, task): """Import hook for fetching lyrics automatically. """ diff --git a/docs/plugins/lyrics.rst b/docs/plugins/lyrics.rst index 5682ddbc0..0c6d68546 100644 --- a/docs/plugins/lyrics.rst +++ b/docs/plugins/lyrics.rst @@ -84,59 +84,40 @@ lyrics will be added to the beets database and, if ``import.write`` is on, embedded into files' metadata. The ``-p`` option to the ``lyrics`` command makes it print lyrics out to the -console so you can view the fetched (or previously-stored) lyrics. The -``-r directory`` option similarly shows all lyrics as an RST (ReStructuredText) -document structure located in ``directory`` (which defaults to the -current directory). That document, in turn, can be parsed by tools like Sphinx -to generate HTML, ePUB or PDF formatted documents. Use, for example, -the following ``conf.py``:: - - # -*- coding: utf-8 -*- - master_doc = 'index' - project = u'Lyrics' - copyright = u'none' - author = u'Various Authors' - latex_documents = [ - (master_doc, 'Lyrics.tex', project, - author, 'manual'), - ] - epub_title = project - epub_author = author - epub_publisher = author - epub_copyright = copyright - epub_exclude_files = ['search.html'] - epub_tocdepth = 1 - epub_tocdup = False - -Then the output can be written to ``index.rst``. An alternative is to -use the following ``index.rst`` file, which will also generate an -index of song titles:: - - Lyrics - ====== - - * :ref:`Song index ` - * :ref:`search` - - Artist index: - - .. toctree:: - :maxdepth: 1 - :glob: - - artists/* - -Then the correct format can be generated with one of:: - - sphinx-build -b epub3 . _build/epub - sphinx-build -b latex . _build/latex - sphinx-build -b html . _build/html +console so you can view the fetched (or previously-stored) lyrics. The ``-f`` option forces the command to fetch lyrics, even for tracks that already have lyrics. Inversely, the ``-l`` option restricts operations to lyrics that are locally available, to show lyrics faster without retrying them over the network all the time. +Rendering lyrics into other formats +----------------------------------- + +The ``-r directory`` option similarly renders all lyrics as an RST +(ReStructuredText) document structure located in ``directory`` (which +defaults to the current directory). That directory, in turn, can be +parsed by tools like Sphinx to generate HTML, ePUB or PDF formatted +documents. A minimal ``conf.py`` and ``index.rst`` files are created +the first time the command is ran, to provide templates that can be +modified. They are not overwritten on subsequent runs. + +Sphinx supports various `builders +`_, but here are a +few suggestions. + + * build a HTML version:: + + sphinx-build -b html . _build/html + + * build an ePUB3 formatted file, usable on ebook-readers:: + + sphinx-build -b epub3 . _build/epub + + * build a PDF file, which incidentally also builds a LaTeX file:: + + sphinx-build -b latex %s _build/latex && make -C _build/latex all-pdf + .. _activate-google-custom-search: Activate Google custom search