Urs Liska <li...@openlilylib.org> 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".