Just playing with this, the funny thing is that RDoc does not copy the
template, but they use hardlinks:
I guess that RPM can't preserve them.
Vít
Dne 20. 07. 22 v 12:28 Vít Ondruch napsal(a):
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.
2) You are using the `--format darkfish`, but wouldn't it be better to
use `--template=NAME` instead?
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.
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.
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/
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 ....
Vít
Dne 04. 07. 22 v 21:23 Jarek Prokop napsal(a):
> Hi all,
>
> I did some initial work in unbundling the static files and adjusting
> the darkfish template that we can then copy out and use for
> generating Fedora's HTML documentation.
>
> For this I used rubygem-rdoc and rdoc v6.4.0 for protyping.
>
> You can check the spec at:
>
https://src.fedoraproject.org/fork/jackorp/rpms/rubygem-rdoc/tree/dedup_s...
> And the RDoc sources at:
>
https://github.com/jackorp/rdoc/tree/fedora_doc_template
>
> To build the RDoc ruby package, you need to build the gem from my
> RDoc fork's branch (which is based on RDoc tag v6.4.0).
>
> To test it, pick any project that makes use of Darkfish for
> documentation and run `RPMBUILD=TRUE rdoc --format darkfish` in the
> project's directory.
> Note that the `RPMBUILD` env variable has to be non empty to force
> symlinking, this is a WIP feature to allow for comparing results.
>
> I used the symlink approach, but it has a few shortcomings, that need
> to be worked around (That is WIP see specfile comment [0]).
> I was able to get the docs to load properly, though, the search index
> generation is broken due to the symlink.
>
> If you are interested in more details of the implementation, scroll
> down for a more detailed explanation.
>
> Also, If you have any notes regarding my approach, feel free to reach
> out and we can discuss.
>
> JFTR, for now I have disabled the test suite as moving the files
> breaks it.
> Copying the static files to proper directories and then removing them
> would be better in general,
> but I use this approach for now to ensure I don't have some files in
> improper locations, during the development of the custom template,
> which could hide some bugs.
>
> Regards,
> Jarek
>
> [0]
>
https://src.fedoraproject.org/fork/jackorp/rpms/rubygem-rdoc/blob/dedup_s...
>
> PS:
> Implementation:
>
> Package:
> All static files were moved to rubygem-rdoc-darkfish-static, which
> has more dependencies, such as the replaced fonts and the web assets
> filesystem.
> The %{_jsdir} and %{_webassetdir} are used to comply with Fedora
> Packaging guidelines [1] [2] which seem relevant to this case.
>
> Fonts.
> To unbundle fonts, I removed them completely. Browsers can load
> them if they are present on other system paths (which is taken care
> of by the `Requires:`).
>
> However, this approach has a shortcoming. If a user generates
> documentation using system RDoc, then fonts will be missing from the
> result directory.
> I'll need to take a closer look to see how to solve this.
>
> Images and CSS stylesheets:
> These are moved to %{_webassetdir} and symlinked to the result
> folder with generated documentation.
>
> Javascript:
> This is more complicated, since RDoc uses gzip compression. We know
> it is going to do that, so it is done ahead of time and the gzip
> files are added to gemspec.
>
> Everything is then moved to proper directories to be symlinked later.
>
> RDoc template:
> Nothing too complicated. The generation and installation (actually
> symlinking) of static files is basically rewritten to satisfy our
> requirements.
> Most of note are the darkfish.rb lines 631 to 663 that contain most
> of the symlinking logic that is then used [3] when the env variable
> is set.
>
> There is one WIP item which is extraction the paths into a variable
> in the ERB template [4].
> The paths are hardcoded now, but there should be a way to make it
> prettier and not hardcoded, but I pushed that back onto TODO, as it
> is not as pressing for developing the template.
>
> [1]
>
https://docs.fedoraproject.org/en-US/packaging-guidelines/JavaScript/
> [2]
>
https://docs.fedoraproject.org/en-US/packaging-guidelines/Web_Assets/
> [3]
>
https://github.com/jackorp/rdoc/commit/de73f599ae44ad95fa2a404caf3a6bdb51...
> [4]
>
https://github.com/jackorp/rdoc/commit/de73f599ae44ad95fa2a404caf3a6bdb51...
> _______________________________________________
> ruby-sig mailing list -- ruby-sig(a)lists.fedoraproject.org
> To unsubscribe send an email to ruby-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.fedoraprojec...
> Do not reply to spam on the list, report it:
>
https://pagure.io/fedora-infrastructure