Sphinx (was: Is a texi2any upgrade still wanted, and what would it take?)

[Jean Abou Samra]

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.)



> > and supports internationalization via po files on top of that. But
> > that is going to be controversial and the amount of work is magnitudes
> > larger :)
> The problem is that an advertised feature set is comparatively useless
> for imagining the amount of work before arriving at a satisfactorily
> smoothly operating and efficient solution.
>
> It is not uncommon to have a proof of concept running within less than a
> week, with a satisfactory efficient solution adding years of
> development.



Yes, I am aware of that. If it were easy, I would have proposed doing this
long ago.