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