Dne 24. 10. 22 v 18:00 Jarek Prokop napsal(a):

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


Of course. But on the +side, we will have the freedom to lag behind upstream and not update at all.


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.


There used to be jQuery, but that was removed several releases ago. I don't think there is high change of CVEs.


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.


The issue I am afraid is that we can't tell if update of RDoc will break the documentation or not. I'd rather keep the old template and have working documentation then the other way around.



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.


Darkfish is quite huge and it even depend on another generator (json_index). Therefore probably the less we differ, the better.



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


Right. I discovered that afterwards. That is good thing :)


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


This  brings the question if in my proof of concept, there should be some bundled provides or not. But what would they be if Darkfish is not exactly standalone project anymore.



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.


The JS files are part of the template and I don't see them being useful for anything else. Although I have not investigated their history ....


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.


Yes, right, this one is certainly part of the generated documentation.



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.


Do I understand correctly that your concern apart of the generated documentation is the RDoc package containing itself the copy of the fonts. That is fair concern.



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.


Yes, RDoc are doing some assumptions. Basically the template must be also placed on Ruby `$LOAD_PATH`.

https://github.com/ruby/rdoc/blob/master/lib/rdoc/options.rb#L1241-L1249




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.


This won't work due to RDoc using hard links:

https://github.com/ruby/rdoc/blob/master/lib/rdoc/generator/darkfish.rb#L584-L599

Basically, the `FileUtils.ln source, destination, **options` fails when the hardlink is attempted to be created from file owned by root to file owned by mockbuild and therefore it falls back to `FileUtils.cp source, destination, **options`

See the other parts of this thread where I have already elaborated about this.


Vít



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


_______________________________________________
ruby-sig mailing list -- ruby-sig@lists.fedoraproject.org
To unsubscribe send an email to ruby-sig-leave@lists.fedoraproject.org
Fedora Code of Conduct: https://docs.fedoraproject.org/en-US/project/code-of-conduct/
List Guidelines: https://fedoraproject.org/wiki/Mailing_list_guidelines
List Archives: https://lists.fedoraproject.org/archives/list/ruby-sig@lists.fedoraproject.org
Do not reply to spam, report it: https://pagure.io/fedora-infrastructure/new_issue