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_static_files
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_static_files/f/rubygem-rdoc.spec#_109
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/de73f599ae44ad95fa2a404caf3a6bdb51fa4425#diff-ddeb55726f649cf3320f376f40db7ca34e75cc0f53765ca8fcef20ca35161bf6R631
[4]
https://github.com/jackorp/rdoc/commit/de73f599ae44ad95fa2a404caf3a6bdb51fa4425#diff-75d0842deb485ab1e0116eb9e2d8257ab952026dac7e541380a254539eb04fa8L10
_______________________________________________
ruby-sig mailing list -- ruby-sig@lists.fedoraproject.org
To unsubscribe send an email to ruby-sig-le...@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 on the list, report it:
https://pagure.io/fedora-infrastructure
