An API documentation generator for Lilypond files
Project description
Lydoc - A Lilypond API documentation generator
##############################################
..
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
##############################################
..
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
Release history Release notifications | RSS feed
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.0.tar.gz
(22.0 kB
view hashes)
Built Distribution
lydoc-0.1.0-py2.py3-none-any.whl
(12.9 kB
view hashes)
Close
Hashes for lydoc-0.1.0-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 9863673e45f124f50c5c3bf41796eb70db608aa39f7071e53abafccf1c48d918 |
|
MD5 | b4a4f93796307bacc0ab5a20011a0f7a |
|
BLAKE2b-256 | 4166f62dbb253f17b6f3a5f865f0f5e9e107a8c67e98344adfb81e632bfc9d9d |