Re: openLilyLib website

[David Kastrup]

Urs Liska <address@hidden> 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".