Package: lydoc
Lydoc - A Lilypond API documentation generator##############################################.. image:: https://img.shields.io/pypi/v/lydoc.svg?maxAge=2592000:target: https://pypi.python.org/pypi/lydoc:alt: PyPI Package.. image:: http://readthedocs.org/projects/lydoc/badge/?version=latest:target: http://lydoc.readthedocs.io/en/latest/?badge=latest:alt: Documentation Status.. image:: https://travis-ci.org/Cecca/lydoc.svg?branch=master:target: https://travis-ci.org/Cecca/lydoc:alt: Continuous Integration..The marker below is used to tell Sphinx where to startto include the README file into the main documentation.. inclusion-markerLydoc is a software that looks for documentation comments in `GNULilypond`_ source files, and outputs API documentation in a variety offormats.-----------------------------------------------------------------------Installation============Lydoc works with both Python 2 (version 2.7 is supported) and Python 3(versions 3.3, 3.4, and 3.5). You can install it in several ways.>From source-----------Clone the repository somewhere on your machine. To install, run fromthe root directory of the project::python setup.py installwhich will install the ``lydoc`` executable, while fetching all thenecessary dependencies in the process. To upgrade, just pull thelatest changes and run the above command again.>From PyPI---------Lydoc is also available on the Python Package Index. You can installit with this single command::pip install --user lydocI recommend running the above command with the ``--user`` option sonot to mess with system packages. If you omit the ``--user`` argument,you might require administration privileges, depending on youmachine's configuration.To upgrade, it is sufficient to run the following command::pip install --user --upgrade lydocVery quick start================Just run the following command::lydoc -o api.rst file.lyto collect documentation from ``file.ly`` and write a ``api.rst`` textfile formatted with `reStructuredText`_.Quick start===========Lydoc will look for documentation comments in the given file ordirectory. In the latter case, it will parse all ``.ly`` and ``.ily``files, recursively. A documentation comment looks like a standardLilypond block comment, with a slightly different opening::%{!% I am a documentation comment :-)%}someFunction =#(define-music-function ...)Note the ``!`` character after the opening of the comment: that's thecharacter that Lydoc uses to distinguish between normal block commentsand documentation ones.So, to extract the documentation from a single file, the command lineis the following::lydoc file.lyThis will output some logging information to standard error, and thecollected documentation on standard output, as a stream of JSONobjects, one per line. This is useful to pipe the output of Lydoc tosome other program, in a machine-friendly format.However, we are humans, not machines, hence we might want to generatesomething more readable, like a file in some lightweight markuplanguage. You have some options:`Markdown`_Arguably the most widespread lightweight markup language::lydoc -o api.md file.ly`reStructuredText`_The markup language used by the powerful `Sphinx`_documentation generator::lydoc -o api.rst file.lyTo generate API documentation for a single lilypond file in`reStructuredText`_ format::lydoc -o api.rst file.lyor in `Markdown`_::lydoc -o api.md file.lyFor more detailed usage instructions, head to the :doc:`/user-manual`page... _`GNU Lilypond`: http://lilypond.org/.. _reStructuredText: http://www.sphinx-doc.org/en/stable/rest.html.. _Markdown: http://daringfireball.net/projects/markdown/.. _Sphinx: http://www.sphinx-doc.org/en/stable/index.html