openLilyLib website

classic Classic list List threaded Threaded
11 messages Options
Reply | Threaded
Open this post in threaded view
|

openLilyLib website

Urs Liska-3
Hi all,

as a starting point for a - hopefully - comprehensive documentation
effort I have finally updated https://openlilylib.org with a completely
new website, which I'd like to have some feedback about and
contributions for.

There are several parts to that effort, most of which are essentially
not started yet.

 * A general introduction website. This is basically complete and
   should finally give a proper introduction about what OLL "is" and
   how it can be made to work
 * Independent sub-sites for each OLL package. These have not been
   written at all, only the links to empty starting pages work without
   404 errors.
 * I've settled with MkDocs (https://www.mkdocs.org), which seems to
   provide what I need, especially a suitable way to hook into and
   extend to our needs.
 * Each sub-site is maintained in a separate Git repository and
   included as a Git submodule, so it should be straightforward to
   manage independent authoring of the documentation by the respective
   package maintainers.
 * There's a link to a contributor's guide, which is also essentially
   empty, except for an entry page.

What I have so far is an infrastructure for textual, Markdown-authored
manuals, although I have already created a plugin for LilyPond syntax
highlighting using python-ly (
https://github.com/uliska/markdown-lilypond/).

What I really *want* to have but have no idea so far how to achieve is
additional code/API documentation retrieved from the actual source
files. There should be a tool to retrieve that from comments (or actual
signatures?), resulting in either HTML or Markdown documentation that
can be automatically integrated in the "manual-style" documentation.

Best
Urs


Reply | Threaded
Open this post in threaded view
|

Re: openLilyLib website

Noeck
Dear Urs,

it’s great that you found time for that. It looks nice and I think
MkDocs is a good choice (would have been my first choice, too).

While speaking about documentation, I very much like this approach:
https://www.divio.com/blog/documentation/

Some nitpicks from me:

- Should everyone see the "Edit this page" pencils?
   - Those links are broken for me
- If you descend into a package documentation, "Home" will not bring you
to openlilylib.org but to the page of the package. While that is
probably a consequence of your fourth bullet point, I find it confusing.
- Do you like the brown color?

>  * Each sub-site is maintained in a separate Git repository and
>    included as a Git submodule, so it should be straightforward to
>    manage independent authoring of the documentation by the respective
>    package maintainers.

While this theoretically makes sense to separate the packages'
documentation, I would run from git submodule. But perhaps your use case
is easier than where my experience comes from and you can still change
that decision later in case it makes things easier.

> What I really *want* to have but have no idea so far how to achieve is
> additional code/API documentation retrieved from the actual source
> files. There should be a tool to retrieve that from comments (or actual
> signatures?),

What do you mean by signatures?
IMHO, this makes sense for "reference-type" documentation in addition to
other parts of the documentation (cf. link at the top).

Cheers,
Joram

Reply | Threaded
Open this post in threaded view
|

Re: openLilyLib website

Urs Liska-3
Hi Joram,

thanks for the ffecback.

Am Donnerstag, den 20.02.2020, 23:33 +0100 schrieb Noeck:
> Dear Urs,
>
> it’s great that you found time for that. It looks nice and I think
> MkDocs is a good choice (would have been my first choice, too).
>
> While speaking about documentation, I very much like this approach:
> https://www.divio.com/blog/documentation/
>

I'll definitely have a look, but only after replying ...

> Some nitpicks from me:
>
> - Should everyone see the "Edit this page" pencils?

Yes. Everybody should be encouraged to join this project ...

>    - Those links are broken for me

... which is of course only possible if the links aren't broken. (
https://github.com/openlilylib-documentation/main-site/issues/1)

> - If you descend into a package documentation, "Home" will not bring
> you
> to openlilylib.org but to the page of the package. While that is
> probably a consequence of your fourth bullet point, I find it
> confusing.

I'm not fully clear how to solve the underlying issue.
In fact "Home" brings you the the home page of the package while "Main
Book" brings you to the top of the whole site. I agree it may be
confusing. The thing is, this site is *not* an actual MkDocs site but a
nested set of MkDocs sites. This brings some additional potential for
more complex set-ups and separation of related sub-books, but it comes
at a cost with complexity.

> - Do you like the brown color?

I haven't given much thought on the colors yet. Each sub-book should
choose its individual color, and the theme has only a limited number of
preconfigured colors (
https://squidfunk.github.io/mkdocs-material/getting-started/#color-palette
). At one point I think we'll want to create a fork of the theme and
add more colors, maybe even with some aesthetic specificity. But that's
nothing that has to be decided at this point. (And I don't dislike that
brown ...).

>
> >  * Each sub-site is maintained in a separate Git repository and
> >    included as a Git submodule, so it should be straightforward to
> >    manage independent authoring of the documentation by the
> > respective
> >    package maintainers.
>
> While this theoretically makes sense to separate the packages'
> documentation, I would run from git submodule. But perhaps your use
> case
> is easier than where my experience comes from and you can still
> change
> that decision later in case it makes things easier.

I don't have any significant experience with submodules. But while I
was always a bit worried about them I think this use case is pretty
safe because we're not talking about libraries some code depends on but
essentially they're independent chunks of content. If a submodule is
out of date or whatever simply that part of the site will look bad or
out of date.

>
> > What I really *want* to have but have no idea so far how to achieve
> > is
> > additional code/API documentation retrieved from the actual source
> > files. There should be a tool to retrieve that from comments (or
> > actual
> > signatures?),
>
> What do you mean by signatures?

AFAICT there are basically two types of source file documentation
systems: retrieving explicit documentation comments (aka docstrings) or
analyzing the defined classes and functions (i.e. their signatures). Or
a combination where the documentation software analyzes the function
signatures but takes comments for their explanations.

> IMHO, this makes sense for "reference-type" documentation in addition
> to
> other parts of the documentation (cf. link at the top).

As said I'll read up on this, but "reference-type" "in addition" sounds
pretty much exactly like what I have in mind.

Best
Urs

>
> Cheers,
> Joram
>


Reply | Threaded
Open this post in threaded view
|

Re: openLilyLib website

Mason Hock-2
In reply to this post by Urs Liska-3
On 02/20, Urs Liska wrote:
> What I really *want* to have but have no idea so far how to achieve is
> additional code/API documentation retrieved from the actual source
> files. There should be a tool to retrieve that from comments (or actual
> signatures?), resulting in either HTML or Markdown documentation that
> can be automatically integrated in the "manual-style" documentation.

Do you want something similar [Sphinx][1] or [Doxygen][2]?  Are the
source files in Scheme, Lilypond, or a combination of both?

[1]: https://en.wikipedia.org/wiki/Sphinx_(documentation_generator)

[2]: https://en.wikipedia.org/wiki/Doxygen

signature.asc (499 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: openLilyLib website

Urs Liska-3
Am Freitag, den 21.02.2020, 18:52 -0800 schrieb [hidden email]:

> On 02/20, Urs Liska wrote:
> > What I really *want* to have but have no idea so far how to achieve
> > is
> > additional code/API documentation retrieved from the actual source
> > files. There should be a tool to retrieve that from comments (or
> > actual
> > signatures?), resulting in either HTML or Markdown documentation
> > that
> > can be automatically integrated in the "manual-style"
> > documentation.
>
> Do you want something similar [Sphinx][1] or [Doxygen][2]?  

Yes, something similar, but IISC these tools (which I had of course
taken notice of earlier) are limited to their set of languages.
Parsing documentation comments or docstrings and producing API
reference is what is still needed.

One aspect that might be different from "traditional" API reference
documentation in a case like openLilyLib (also like LaTeX packages) is
that there are *end-user*-facing commands and *internal* commands.
Internal commands (i.e. auxiliary functions) may or may not be
interesting for users outside the package development, but probably the
documentation should be kept separate in some way. For example by
providing totally separate pages/trees or listing the end-user
functionality first on a page, followed by the internal stuff. In
addition I think the end-user functionality whould be documented on a
package-based page while the internal API should be documented per
source file. But I haven't fully thought through that topic yet.

Craig Dabelstein did some research and suggested NaturalDocs (
https://www.naturaldocs.org/) which looks nice and suitably
extensible/configurable for our purpose. I'm a little bit wary about
the fact that it's a project with a single contributor, and I know what
I'm talking about ...
(also I *think* it would be good to have a Python-based tool because it
might be easier to extend and to integrate with the other stuff.

> Are the
> source files in Scheme, Lilypond, or a combination of both?

Of course both.
The end-user interface is usually LilyPond, but the functionality is
all LilyPond, Scheme-in-LilyPond, and Scheme-in-Scheme-files.

Urs

>
> [1]: https://en.wikipedia.org/wiki/Sphinx_(documentation_generator)
>
> [2]: https://en.wikipedia.org/wiki/Doxygen


Reply | Threaded
Open this post in threaded view
|

Re: openLilyLib website

Simon Albrecht-2
In reply to this post by Urs Liska-3
Hi Urs,

this looks great! As often, I can’t offer much more than applause and
some nitpicking…

On the ‘About LilyPond’ I’d rather write “GNU LilyPond is a music
notation program /strongly inspired by/ traditional craftsmanship”.
After all, the process of working with LilyPond doesn’t resemble
traditional craftsmanship at all…

The use of the word ‘domain’ in the About/LilyPond and /openLilyLib
seems quite technical considering IIUC the site is supposed to be read
also by people without a background in software development…

‘Get started/Install openLilyLib’ has an instance of [oll-core} that
seems unintentional.

s/documenation/documentation

… but generally, the texts seem very appropriate and useful :-)

Very best regards
Simon

On 20.02.20 22:44, Urs Liska wrote:

> Hi all,
>
> as a starting point for a - hopefully - comprehensive documentation
> effort I have finally updated https://openlilylib.org with a completely
> new website, which I'd like to have some feedback about and
> contributions for.
>
> There are several parts to that effort, most of which are essentially
> not started yet.
>
>   * A general introduction website. This is basically complete and
>     should finally give a proper introduction about what OLL "is" and
>     how it can be made to work
>   * Independent sub-sites for each OLL package. These have not been
>     written at all, only the links to empty starting pages work without
>     404 errors.
>   * I've settled with MkDocs (https://www.mkdocs.org), which seems to
>     provide what I need, especially a suitable way to hook into and
>     extend to our needs.
>   * Each sub-site is maintained in a separate Git repository and
>     included as a Git submodule, so it should be straightforward to
>     manage independent authoring of the documentation by the respective
>     package maintainers.
>   * There's a link to a contributor's guide, which is also essentially
>     empty, except for an entry page.
>
> What I have so far is an infrastructure for textual, Markdown-authored
> manuals, although I have already created a plugin for LilyPond syntax
> highlighting using python-ly (
> https://github.com/uliska/markdown-lilypond/).
>
> What I really *want* to have but have no idea so far how to achieve is
> additional code/API documentation retrieved from the actual source
> files. There should be a tool to retrieve that from comments (or actual
> signatures?), resulting in either HTML or Markdown documentation that
> can be automatically integrated in the "manual-style" documentation.
>
> Best
> Urs
>
>

Reply | Threaded
Open this post in threaded view
|

Re: openLilyLib website

Mason Hock-2
In reply to this post by Urs Liska-3
On 02/22, Urs Liska wrote:
> Am Freitag, den 21.02.2020, 18:52 -0800 schrieb [hidden email]:
> > Do you want something similar [Sphinx][1] or [Doxygen][2]?  
>
> Yes, something similar, but IISC these tools (which I had of course
> taken notice of earlier) are limited to their set of languages.

Yes, that's right.  I wasn't recommending those tools, just confirming
that you are looking for something similar.

> Craig Dabelstein did some research and suggested NaturalDocs (
> https://www.naturaldocs.org/) which looks nice and suitably
> extensible/configurable for our purpose. I'm a little bit wary about
> the fact that it's a project with a single contributor, and I know what
> I'm talking about ...
> (also I *think* it would be good to have a Python-based tool because it
> might be easier to extend and to integrate with the other stuff.
>
> > Are the
> > source files in Scheme, Lilypond, or a combination of both?
>
> Of course both.
> The end-user interface is usually LilyPond, but the functionality is
> all LilyPond, Scheme-in-LilyPond, and Scheme-in-Scheme-files.
Huh.  I thought it would be easier to find a good documentation
generator for Scheme, but after searching for a while everything I found
appears to have gone unmaintained for at least a few years (which I'm
guessing is what you're afraid could happen with NaturalDocs?), and
other than NaturalDocs I couldn't find anything that supports
configuration for arbitrary languages.

signature.asc (499 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: openLilyLib website

David Kastrup
In reply to this post by Urs Liska-3
Urs Liska <[hidden email]> writes:

> Hi all,
>
> as a starting point for a - hopefully - comprehensive documentation
> effort I have finally updated https://openlilylib.org with a completely
> new website, which I'd like to have some feedback about and
> contributions for.
>
> There are several parts to that effort, most of which are essentially
> not started yet.
>
>  * A general introduction website. This is basically complete and
>    should finally give a proper introduction about what OLL "is" and
>    how it can be made to work
>  * Independent sub-sites for each OLL package. These have not been
>    written at all, only the links to empty starting pages work without
>    404 errors.
>  * I've settled with MkDocs (https://www.mkdocs.org), which seems to
>    provide what I need, especially a suitable way to hook into and
>    extend to our needs.
>  * Each sub-site is maintained in a separate Git repository and
>    included as a Git submodule, so it should be straightforward to
>    manage independent authoring of the documentation by the respective
>    package maintainers.
>  * There's a link to a contributor's guide, which is also essentially
>    empty, except for an entry page.
>
> What I have so far is an infrastructure for textual, Markdown-authored
> manuals, although I have already created a plugin for LilyPond syntax
> highlighting using python-ly (
> https://github.com/uliska/markdown-lilypond/).
>
> What I really *want* to have but have no idea so far how to achieve is
> additional code/API documentation retrieved from the actual source
> files. There should be a tool to retrieve that from comments (or actual
> signatures?), resulting in either HTML or Markdown documentation that
> can be automatically integrated in the "manual-style" documentation.

With regard to the LilyPond-book/Texinfo route, it might be worth
considering that Asciidoc (which Git documentation is written in) can be
converted via the route (grabbed lines from the git Documentation
Makefile):

user-manual.texi: user-manual.xml
        $(QUIET_DB2TEXI)$(RM) $@+ $@ && \
        $(DOCBOOK2X_TEXI) user-manual.xml --encoding=UTF-8 --to-stdout >$@++ && \
        $(PERL_PATH) fix-texi.perl <$@++ >$@+ && \
        rm $@++ && \
        mv $@+ $@

user-manual.xml: user-manual.txt user-manual.conf
        $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \
        $(TXT_TO_XML) -d book -o $@+ $< && \
        mv $@+ $@

ASCIIDOC = asciidoc
ASCIIDOC_EXTRA =
ASCIIDOC_HTML = xhtml11
ASCIIDOC_DOCBOOK = docbook
ASCIIDOC_CONF = -f asciidoc.conf
ASCIIDOC_COMMON = $(ASCIIDOC) $(ASCIIDOC_EXTRA) $(ASCIIDOC_CONF) \
                -agit_version=$(GIT_VERSION)
TXT_TO_HTML = $(ASCIIDOC_COMMON) -b $(ASCIIDOC_HTML)
TXT_TO_XML = $(ASCIIDOC_COMMON) -b $(ASCIIDOC_DOCBOOK)

DOCBOOK2X_TEXI = docbook2x-texi

So that's a bunch of stuff that can convert via Docbook XML to Texinfo.
And it's likely that some Wiki-acceptable format convertable to Docbook
XML exists.

--
David Kastrup
My replies have a tendency to cause friction.  To help mitigating
damage, feel free to forward problematic posts to me adding a subject
like "timeout 1d" (for a suggested timeout of 1 day) or "offensive".

Reply | Threaded
Open this post in threaded view
|

Re: openLilyLib website

Urs Liska-3
In reply to this post by Simon Albrecht-2
Hi Simon,

Am Sonntag, den 23.02.2020, 18:42 +0100 schrieb Simon Albrecht:
> Hi Urs,
>
> this looks great! As often, I can’t offer much more than applause
> and
> some nitpicking…

Well, that's useful too.

>
> On the ‘About LilyPond’ I’d rather write “GNU LilyPond is a music
> notation program /strongly inspired by/ traditional craftsmanship”.
> After all, the process of working with LilyPond doesn’t resemble
> traditional craftsmanship at all…

Good point.

>
> The use of the word ‘domain’ in the About/LilyPond and /openLilyLib
> seems quite technical considering IIUC the site is supposed to be
> read
> also by people without a background in software development…

I must say I'm pretty unhappy with that whole page. I actually replaced
the bullet list with some text just to be able to send that email to
the list.

The introduction on that page should be even shorter, but at the same
time more friendly, casual, positively inspiring than the current text
tending to be too technical and boring.

>
> ‘Get started/Install openLilyLib’ has an instance of [oll-core} that
> seems unintentional.

Thanks, had already been spotted and fixed (although not uploaded yet).

>
> s/documenation/documentation

Thanks.

Best
Urs

>
> … but generally, the texts seem very appropriate and useful :-)
>
> Very best regards
> Simon
>
> On 20.02.20 22:44, Urs Liska wrote:
> > Hi all,
> >
> > as a starting point for a - hopefully - comprehensive documentation
> > effort I have finally updated https://openlilylib.org with a
> > completely
> > new website, which I'd like to have some feedback about and
> > contributions for.
> >
> > There are several parts to that effort, most of which are
> > essentially
> > not started yet.
> >
> >   * A general introduction website. This is basically complete and
> >     should finally give a proper introduction about what OLL "is"
> > and
> >     how it can be made to work
> >   * Independent sub-sites for each OLL package. These have not been
> >     written at all, only the links to empty starting pages work
> > without
> >     404 errors.
> >   * I've settled with MkDocs (https://www.mkdocs.org), which seems
> > to
> >     provide what I need, especially a suitable way to hook into and
> >     extend to our needs.
> >   * Each sub-site is maintained in a separate Git repository and
> >     included as a Git submodule, so it should be straightforward to
> >     manage independent authoring of the documentation by the
> > respective
> >     package maintainers.
> >   * There's a link to a contributor's guide, which is also
> > essentially
> >     empty, except for an entry page.
> >
> > What I have so far is an infrastructure for textual, Markdown-
> > authored
> > manuals, although I have already created a plugin for LilyPond
> > syntax
> > highlighting using python-ly (
> > https://github.com/uliska/markdown-lilypond/).
> >
> > What I really *want* to have but have no idea so far how to achieve
> > is
> > additional code/API documentation retrieved from the actual source
> > files. There should be a tool to retrieve that from comments (or
> > actual
> > signatures?), resulting in either HTML or Markdown documentation
> > that
> > can be automatically integrated in the "manual-style"
> > documentation.
> >
> > Best
> > Urs
> >
> >


Reply | Threaded
Open this post in threaded view
|

Re: openLilyLib website

Urs Liska-3
In reply to this post by David Kastrup
Hi David,

Am Sonntag, den 23.02.2020, 22:12 +0100 schrieb David Kastrup:

> Urs Liska <[hidden email]> writes:
>
> > Hi all,
> >
> > as a starting point for a - hopefully - comprehensive documentation
> > effort I have finally updated https://openlilylib.org with a
> > completely
> > new website, which I'd like to have some feedback about and
> > contributions for.
> >
> > There are several parts to that effort, most of which are
> > essentially
> > not started yet.
> >
> >  * A general introduction website. This is basically complete and
> >    should finally give a proper introduction about what OLL "is"
> > and
> >    how it can be made to work
> >  * Independent sub-sites for each OLL package. These have not been
> >    written at all, only the links to empty starting pages work
> > without
> >    404 errors.
> >  * I've settled with MkDocs (https://www.mkdocs.org), which seems
> > to
> >    provide what I need, especially a suitable way to hook into and
> >    extend to our needs.
> >  * Each sub-site is maintained in a separate Git repository and
> >    included as a Git submodule, so it should be straightforward to
> >    manage independent authoring of the documentation by the
> > respective
> >    package maintainers.
> >  * There's a link to a contributor's guide, which is also
> > essentially
> >    empty, except for an entry page.
> >
> > What I have so far is an infrastructure for textual, Markdown-
> > authored
> > manuals, although I have already created a plugin for LilyPond
> > syntax
> > highlighting using python-ly (
> > https://github.com/uliska/markdown-lilypond/).
> >
> > What I really *want* to have but have no idea so far how to achieve
> > is
> > additional code/API documentation retrieved from the actual source
> > files. There should be a tool to retrieve that from comments (or
> > actual
> > signatures?), resulting in either HTML or Markdown documentation
> > that
> > can be automatically integrated in the "manual-style"
> > documentation.
>

I must admit I don't fully understand what your comments are actually
targeted at.

> With regard to the LilyPond-book/Texinfo route, it might be worth
> considering that Asciidoc (which Git documentation is written in) can
> be
> converted via the route (grabbed lines from the git Documentation
> Makefile):
>
> user-manual.texi: user-manual.xml
> $(QUIET_DB2TEXI)$(RM) $@+ $@ && \
> $(DOCBOOK2X_TEXI) user-manual.xml --encoding=UTF-8 --to-stdout
> >$@++ && \
> $(PERL_PATH) fix-texi.perl <$@++ >$@+ && \
> rm $@++ && \
> mv $@+ $@
>
> user-manual.xml: user-manual.txt user-manual.conf
> $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \
> $(TXT_TO_XML) -d book -o $@+ $< && \
> mv $@+ $@
>
> ASCIIDOC = asciidoc
> ASCIIDOC_EXTRA =
> ASCIIDOC_HTML = xhtml11
> ASCIIDOC_DOCBOOK = docbook
> ASCIIDOC_CONF = -f asciidoc.conf
> ASCIIDOC_COMMON = $(ASCIIDOC) $(ASCIIDOC_EXTRA) $(ASCIIDOC_CONF) \
> -agit_version=$(GIT_VERSION)
> TXT_TO_HTML = $(ASCIIDOC_COMMON) -b $(ASCIIDOC_HTML)
> TXT_TO_XML = $(ASCIIDOC_COMMON) -b $(ASCIIDOC_DOCBOOK)
>
> DOCBOOK2X_TEXI = docbook2x-texi
>
> So that's a bunch of stuff that can convert via Docbook XML to
> Texinfo.
> And it's likely that some Wiki-acceptable format convertable to
> Docbook
> XML exists.

I've had a look at the Asciidoc homepage, and it looks like a tool I
might like.

But at this point we are talking about HTML targets (possibly PDF too),
Markdown files and documentation generated from LilyPond/Scheme files.
Nothing about DocBook, texidoc etc.

What are you actually intending to convey with these Makefile excerpts?
That I should consider AsciiDoc as a possible platform for the
documentation? What would be in there that makes it a (better and)
suitable tool for the task?
(This is not meant as an objection [somewhat hard to express], rather a
request for clarification. I need more a more concrete idea what you
want me to consider.)

Urs

>


Reply | Threaded
Open this post in threaded view
|

Re: openLilyLib website

David Kastrup
Urs Liska <[hidden email]> writes:

> Hi David,
>
> Am Sonntag, den 23.02.2020, 22:12 +0100 schrieb David Kastrup:
>> Urs Liska <[hidden email]> writes:
>>
>> > Hi all,
>> >
>> > as a starting point for a - hopefully - comprehensive documentation
>> > effort I have finally updated https://openlilylib.org with a
>> > completely
>> > new website, which I'd like to have some feedback about and
>> > contributions for.
>> >
>> > There are several parts to that effort, most of which are
>> > essentially
>> > not started yet.
>> >
>> >  * A general introduction website. This is basically complete and
>> >    should finally give a proper introduction about what OLL "is"
>> > and
>> >    how it can be made to work
>> >  * Independent sub-sites for each OLL package. These have not been
>> >    written at all, only the links to empty starting pages work
>> > without
>> >    404 errors.
>> >  * I've settled with MkDocs (https://www.mkdocs.org), which seems
>> > to
>> >    provide what I need, especially a suitable way to hook into and
>> >    extend to our needs.
>> >  * Each sub-site is maintained in a separate Git repository and
>> >    included as a Git submodule, so it should be straightforward to
>> >    manage independent authoring of the documentation by the
>> > respective
>> >    package maintainers.
>> >  * There's a link to a contributor's guide, which is also
>> > essentially
>> >    empty, except for an entry page.
>> >
>> > What I have so far is an infrastructure for textual, Markdown-
>> > authored
>> > manuals, although I have already created a plugin for LilyPond
>> > syntax
>> > highlighting using python-ly (
>> > https://github.com/uliska/markdown-lilypond/).
>> >
>> > What I really *want* to have but have no idea so far how to achieve
>> > is
>> > additional code/API documentation retrieved from the actual source
>> > files. There should be a tool to retrieve that from comments (or
>> > actual
>> > signatures?), resulting in either HTML or Markdown documentation
>> > that
>> > can be automatically integrated in the "manual-style"
>> > documentation.
>>
>
> I must admit I don't fully understand what your comments are actually
> targeted at.
>
>> With regard to the LilyPond-book/Texinfo route, it might be worth
>> considering that Asciidoc (which Git documentation is written in) can
>> be
>> converted via the route (grabbed lines from the git Documentation
>> Makefile):
>>
>> user-manual.texi: user-manual.xml
>> $(QUIET_DB2TEXI)$(RM) $@+ $@ && \
>> $(DOCBOOK2X_TEXI) user-manual.xml --encoding=UTF-8 --to-stdout
>> >$@++ && \
>> $(PERL_PATH) fix-texi.perl <$@++ >$@+ && \
>> rm $@++ && \
>> mv $@+ $@
>>
>> user-manual.xml: user-manual.txt user-manual.conf
>> $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \
>> $(TXT_TO_XML) -d book -o $@+ $< && \
>> mv $@+ $@
>>
>> ASCIIDOC = asciidoc
>> ASCIIDOC_EXTRA =
>> ASCIIDOC_HTML = xhtml11
>> ASCIIDOC_DOCBOOK = docbook
>> ASCIIDOC_CONF = -f asciidoc.conf
>> ASCIIDOC_COMMON = $(ASCIIDOC) $(ASCIIDOC_EXTRA) $(ASCIIDOC_CONF) \
>> -agit_version=$(GIT_VERSION)
>> TXT_TO_HTML = $(ASCIIDOC_COMMON) -b $(ASCIIDOC_HTML)
>> TXT_TO_XML = $(ASCIIDOC_COMMON) -b $(ASCIIDOC_DOCBOOK)
>>
>> DOCBOOK2X_TEXI = docbook2x-texi
>>
>> So that's a bunch of stuff that can convert via Docbook XML to
>> Texinfo.
>> And it's likely that some Wiki-acceptable format convertable to
>> Docbook
>> XML exists.
>
> I've had a look at the Asciidoc homepage, and it looks like a tool I
> might like.
>
> But at this point we are talking about HTML targets (possibly PDF too),
> Markdown files and documentation generated from LilyPond/Scheme files.
> Nothing about DocBook, texidoc etc.
>
> What are you actually intending to convey with these Makefile excerpts?
> That I should consider AsciiDoc as a possible platform for the
> documentation? What would be in there that makes it a (better and)
> suitable tool for the task?
> (This is not meant as an objection [somewhat hard to express], rather a
> request for clarification. I need more a more concrete idea what you
> want me to consider.)

Basically this boils down to pointing out that Texinfo, which has some
prominence in the LilyPond core, has conversion paths via docbook2x-texi
from formats that are more akin to what one would use automated
documentation extraction on.

That's all.  I have not enough clue about openLilyLib to figure out
whether that information might be useful for you.  I just threw that out
and it would seem like I made it sound like more (or something
different) than it actually is.  Just some keyword-triggered info that
may or may not be interesting for whatever this conversation I barreled
in was about.

Sorry if it's just nonsense and occupied too much of your time trying to
make sense of.

David

--
David Kastrup
My replies have a tendency to cause friction.  To help mitigating
damage, feel free to forward problematic posts to me adding a subject
like "timeout 1d" (for a suggested timeout of 1 day) or "offensive".