Re: Sphinx

[David Kastrup]

Jean Abou Samra <jean@abou-samra.fr> writes:

> Le 24/10/2022 à 20:00, David Kastrup a écrit :
>> Jean Abou Samra <jean@abou-samra.fr> writes:
>>
>>> Personally, my dream would be to switch to a different documentation
>>> tool entirely, like Sphinx, which supports HTML, LaTeX and Texinfo
>>> output, with extensive HTML customization possibilities, and would
>>> not need so much build system fuss (lilypond-book etc.),
>> How do you imagine the LilyPond images to arrive in the documentation
>> without the "build system fuss"?  The bulk of the lilypond-book fuss is
>> about efficiently compiling ten thousands of small LilyPond fragments
>> without recompiling duplicates appearing in multiple translations.
>
>
>
> Sphinx supports arbitrary roles and directives, which are similar to
> Texinfo commands and environments. Texinfo has macros, but they can't
> capture the literal input without Texinfo macro expansion (@verbatim is
> special and you could not redefine it as a custom macro), and they don't
> have a programming language available to them. In Sphinx, this is just
> a matter of reading the LilyPond input in a Python extension and inserting
> the output at that point, as is already done in
>
> https://pypi.org/project/sphinxcontrib-lilypond/
> or the alternative
> https://github.com/sphinx-notes/lilypond
>
> Which means that there is no longer a need to parse and pre-process
> the source ourselves with regexes in lilypond-book, with the associated
> build system fuss. Everything remains in the .rst or .md source files.
> There is a built-in mechanism for serialisation of the build environment
> and documentation data structures, using the Python pickle module,
> so I think you can add the images to that in order to cache them and
> worry less about how to store the cache on the disk. (But I'm not
> an expert and I didn't study the extensions linked above that
> extensively.)
>
> Plus, dependency management across multiple files is built-in,
> so you don't need to define the build process in Makefiles yourself.
> (Extensions can hook into that.)

I think you'd be seriously seriously surprised at the difference in
efficiency when _not_ deduplicating snippets and rolling hundreds of
them into a single LilyPond call.

The basics of lilypond-book where you can think of how to map them to
Spinx are not the ones responsible for doing the really heavy lifting.

-- 
David Kastrup