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#L...
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(a)lists.fedoraproject.org
To unsubscribe send an email toruby-sig-leave(a)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.fed...
Do not reply to spam, report it:https://pagure.io/fedora-infrastructure/new_issue