Hi,
Just a few notes from the limited time I spend trying to understand the approach.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.
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.
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.
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.
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 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.
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/
Hmm... this might either just work with only edits to templates (which would be great) or we will have to modify the generator.
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 ....
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