Skip to main content

An API documentation generator for Lilypond files

Project description

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 start
to include the README file into the main documentation

.. inclusion-marker

Lydoc is a software that looks for documentation comments in `GNU
Lilypond`_ source files, and outputs API documentation in a variety of
formats.

-----------------------------------------------------------------------

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 from
the root directory of the project::

python setup.py install

which will install the ``lydoc`` executable, while fetching all the
necessary dependencies in the process. To upgrade, just pull the
latest changes and run the above command again.

>From PyPI
---------

Lydoc is also available on the Python Package Index. You can install
it with this single command::

pip install --user lydoc

I recommend running the above command with the ``--user`` option so
not to mess with system packages. If you omit the ``--user`` argument,
you might require administration privileges, depending on you
machine's configuration.

To upgrade, it is sufficient to run the following command::

pip install --user --upgrade lydoc

Very quick start
================

Just run the following command::

lydoc -o api.rst file.ly

to collect documentation from ``file.ly`` and write a ``api.rst`` text
file formatted with `reStructuredText`_.

Quick start
===========

Lydoc will look for documentation comments in the given file or
directory. In the latter case, it will parse all ``.ly`` and ``.ily``
files, recursively. A documentation comment looks like a standard
Lilypond 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 the
character that Lydoc uses to distinguish between normal block comments
and documentation ones.

So, to extract the documentation from a single file, the command line
is the following::

lydoc file.ly

This will output some logging information to standard error, and the
collected documentation on standard output, as a stream of JSON
objects, one per line. This is useful to pipe the output of Lydoc to
some other program, in a machine-friendly format.

However, we are humans, not machines, hence we might want to generate
something more readable, like a file in some lightweight markup
language. 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.ly


To generate API documentation for a single lilypond file in
`reStructuredText`_ format::

lydoc -o api.rst file.ly

or in `Markdown`_::

lydoc -o api.md file.ly


For 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

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

lydoc-0.1.1.tar.gz (22.8 kB view details)

Uploaded Source

Built Distribution

lydoc-0.1.1-py2.py3-none-any.whl (14.0 kB view details)

Uploaded Python 2Python 3

File details

Details for the file lydoc-0.1.1.tar.gz.

File metadata

  • Download URL: lydoc-0.1.1.tar.gz
  • Upload date:
  • Size: 22.8 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No

File hashes

Hashes for lydoc-0.1.1.tar.gz
Algorithm Hash digest
SHA256 b20ed39c7f06c3278372f06012c7c95df11592cce851cb555702c0a5899c4c72
MD5 2c706176b1bc6dfa7747bd2129d127b2
BLAKE2b-256 7fb2774cab34795868241df9a7bbf20c74ab42c49bb99c4c0c50719eeadbf885

See more details on using hashes here.

File details

Details for the file lydoc-0.1.1-py2.py3-none-any.whl.

File metadata

File hashes

Hashes for lydoc-0.1.1-py2.py3-none-any.whl
Algorithm Hash digest
SHA256 571fbfe6df9548317ad42b14ad850b4f4c708659d2b6f218ca951fc4005e2cb7
MD5 f6d6e74c86c83a209cbc5f1eb87e0bc0
BLAKE2b-256 af6549464c73f18a51c0d07cef18c498e2a907b895be62ce55297fdf2bd83454

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page