Hi,
On 7/20/22 12:28, Vít Ondruch wrote:
Just a few notes from the limited time I spend trying to understand
the approach.
1) The template can't be subpackage of the rubygem-rdoc. It needs to
live in completely separate project to enable us to decouple RDoc
updates from the template updates.
But then we will have to keep up with updates to
darkfish and update it
by hand should there be some CVE in the template if we won't want to
have it part of rubygem-rdoc.
Not sure how much of an issue would that be, if that is an acceptable
tradeoff, there isn't much of a problem with keeping it as a separate
package IMO.
2) You are using the `--format darkfish`, but wouldn't it be better to
use `--template=NAME` instead?
As I return to it, I understand the difference between RDoc generator vs
template a bit better :).
`--template` is probably a usable approach as long as we don't want to
customize some other assets or their paths in the generator's internals
too much.
3) I don't think we necessarily need to use the `%{_webassetdir}` or
`%{_jsdir}` dirs. OTOH, the template is using jQuery, which resides in
the `%{_jsdir}`, isn't it? But I can't see any reference to jQuery.
AFAICT it does not seem to be using JQuery for some time, Darkfish
contains its own JS (and CSS) now, which I view as another issue to solve,
since we are essentially not only bundling fonts but also the darkfish's JS.
That is the motivation for splitting out the files into these
directories. As there are JS/CSS files that come with a doc subpackage,
and our motivation is to have HTML viewable in the browser, I followed
these guidelines:
For CSS:
https://docs.fedoraproject.org/en-US/packaging-guidelines/Web_Assets/
And for JS:
https://docs.fedoraproject.org/en-US/packaging-guidelines/JavaScript/
So the question is, what are darkfish JS files, that would probably
decide which directory will we keep them in.
But it gets even more "interesting". Only some files that are like that
can be simply factored out into a single reusable file, since the
Darkfish generates a search index
for the specific package for the functions, modules and whatnot, which
deserves its own directory.
4) I would not mind to keep the original template including the
bundled fonts around. The original functionality including usage of
the original template for generating the documentation should be
completely preserved.
I feel we would not resolve the issue at hand fully.
Moreover, the
generator can copy out the fonts provided by RPMs, provided they are
installed.
5) There is too much changes into the RDoc. If possible, I think it
would be better to keep the RDoc in its pristine form. I'd rather
seems some RPM macro to do some replacements if needed. But I still
think that if the template was done smart and it would e.g. already
contained symlinks, so copying of files would be in reality copying of
symlinks, that could save us from the modifications. IOW my naive idea
is:
/some/path/to/our/template/ - This patch contains our version of Darkfish
/some/path/to/template/which/contains/just/symlinks/to/template/ - As
the path says, this on the first look appears to be the template, but
in reality these are just symlinks.
$ rdoc
--template=/some/path/to/template/which/contains/just/symlinks/to/template/
I think
rdoc uses the name of template it pulls from somewhere and
specifying path like this does not work. At least not for me locally.
And the end result should be:
~~~
/usr/share/gems/doc/rdoc-6.3.2/rdoc/js/darkfish.js ->
/some/path/to/our/template/js/darkfish.js
~~~
But this might not be realistic at all ....
Hmm... this might either just work with
only edits to templates (which
would be great) or we will have to modify the generator.
I plan to create a copr (hopefully) this week with some possible
approaches. I'll share it here once I have it at least partially running.
Regards,
Jarek