Skip to content

Move documentation into template includes #18

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Closed
wants to merge 1 commit into from
Closed

Move documentation into template includes #18

wants to merge 1 commit into from

Conversation

muellerj
Copy link

No description provided.

@jeremyevans
Copy link
Owner

Thank you for taking the time to submit a patch. However, I don't want to list how to do add locals for every template engine tilt supports to the README. The only reason that there are two examples instead of a single example now is that doing so for string templates is not obvious even if you know how string templates work. As doing so for slim templates is obvious if you know how slim templates work, I don't want to add examples for slim (or other template libraries).

I have been thinking about expanding the documentation for each template library, and this would be a good thing to mention on a slim-specific documentation page. Would you be interested in working on a general documentation refactoring?

@muellerj
Copy link
Author

muellerj commented Jun 11, 2025 via email

@jeremyevans
Copy link
Owner

I was thinking of having comments at the top of each template engine file, with all of the details for the template engine. RDoc will render these as file-level documentation, and we could have the README link to each page using rdoc-ref. We currently have some template details in doc/TEMPLATES.md. The template-engine specific documentation could be moved to the template files, and the non-template-engine specific documentation could be moved to the README if it is useful and not redundant.

@muellerj
Copy link
Author

muellerj commented Jun 11, 2025 via email

@muellerj muellerj closed this Jun 11, 2025
@muellerj
Copy link
Author

@jeremyevans: Sorry to bother you, but can you elaborate on the rdoc-ref links? I've put together a branch at https://github.com/muellerj/tilt/tree/docs-refactoring?tab=readme-ov-file, but linking to lib/slim.rb is not what you had in mind, correct?

@jeremyevans
Copy link
Owner

Actually, linking to lib/slim.rb was what I had in mind, since that's where the documentation would be. In rdoc format, this would be: {Slim}[rdoc-ref:lib/slim.rb]. I'm not sure how you get the same behavior in markdown format.

Note that GitHub doesn't handle rdoc-ref. The plan is to use rdoc to build the documentation website, and host the website on GitHub Pages.

@muellerj
Copy link
Author

I got as far as linking to the page via {Slim}[rdoc-ref:Tilt::SlimTemplate] and then having lib/tilt/slim.rb (as an example for the other template engine files) look like this:

# frozen_string_literal: true

require_relative 'template'
require 'slim'

module Tilt
  # Some details about the slim engine
  #
  # == Embedded locals
  #
  # In slim templates, the comment format looks like this:
  #
  #   //# locals: ()

  class SlimTemplate < Slim::Template
  end
end

It's not ideal since it changes SlimTemplate to be a descendant of Slim::Template rather than assigning the class directly, but I was not able to get RDoc to generate the file otherwise. Please let me know if this is acceptable.

@jeremyevans
Copy link
Owner

Does {Slim}[rdoc-ref:lib/tilt/slim.rb] not work to link to the file-level documentation?

@muellerj
Copy link
Author

muellerj commented Jun 12, 2025 via email

@jeremyevans
Copy link
Owner

I don't want to waste your time. I'll see if I can get a basic framework working in the next few days. If that is successful, then it would just require the drudge work of moving and writing documentation. If I cannot get it to work, I'll need to choose a different approach.

@jeremyevans
Copy link
Owner

It's not you, it's a bug or limitation in rdoc. rdoc-ref allows linking to non-.rb files, but apparently does not allow linking to .rb files. The behavior may be intentional, but it seems undesirable to me. I'll send a PR to rdoc and see what they think.

@jeremyevans
Copy link
Owner

rdoc PR: ruby/rdoc#1376

@muellerj
Copy link
Author

muellerj commented Sep 4, 2025

I just checked back here and noticed that your rdoc PR was merged. I'll take a 2nd stab at this in the coming days.

@jeremyevans
Copy link
Owner

Awesome, thanks for following up!

@muellerj
Copy link
Author

muellerj commented Sep 5, 2025

I'm still not getting the desired files to be created, but maybe I'm just being thick:

❯ rdoc --version
6.14.2-pre            # my local installation to have stuff from master

❮ cat lib/tilt/slim.rb
# frozen_string_literal: true
require_relative 'template'
require 'slim'

# Some details about the slim engine
#
# == Embedded locals
#
# In slim templates, the comment format looks like this:
#
#   //# locals: ()

Tilt::SlimTemplate = Slim::Template

❯ ag Slim README.md
52:| {Slim}[rdoc-ref:lib/tilt/slim.rb]         | .slim                  | slim                          |

❯ rdoc
Parsing sources...
100% [46/46]  /Users/muellerj/src/tilt/lib/tilt/yajl.rb

Generating Darkfish format into /Users/muellerj/src/tilt/doc...

You can visit the home page at: file:///Users/muellerj/src/tilt/doc/index.html

  Files:       46

  Classes:     25 ( 5 undocumented)
  Modules:      4 ( 1 undocumented)
  Constants:   26 (11 undocumented)
  Attributes:  12 ( 2 undocumented)
  Methods:    114 (63 undocumented)

  Total:      181 (82 undocumented)
   54.70% documented

  Elapsed: 0.6s


❯ ag Slim doc/README_md.html
304:<td><a href="lib/tilt/slim_rb.html">Slim</a></td>

❯ ls doc/lib/tilt
ls: doc/lib/tilt: No such file or directory

❯ ag slim doc
doc/created.rid
42:/Users/muellerj/src/tilt/lib/tilt/slim.rb    Fri, 05 Sep 2025 09:39:25 +0200

doc/CHANGELOG_md.html
238:<p>Ship slim template support with tilt (minad) (#4)</p>
418:<p>Add Slim as an external template engine (judofyr)</p>

doc/Tilt.html
175:        <dt id="SlimTemplate">SlimTemplate
177:          <p>Some details about the slim engine</p>
181:<p>In slim templates, the comment format looks like this:</p>

doc/README_md.html
304:<td><a href="lib/tilt/slim_rb.html">Slim</a></td>
305:<td>.slim</td>
306:<td>slim</td>

Note how the link to lib/tilt/slim_rb.html is created but the file is not and documentation content in lib/tilt/slim.rb gets "attributed" to SlimTemplate. Am I missing something?

@jeremyevans
Copy link
Owner

Install the hanna gem, and use rdoc -f hanna when building the documentation. Darkfish (rdoc's default template) doesn't create the necessary pages. My rdoc PR originally fixed Darkfish, but the rdoc maintainer asked to have Darkfish not render the pages, so I reverted those changes. All of my libraries use hanna to render rdoc.

@muellerj muellerj changed the title Add instructions for embedded locals in slim Move documentation into template includes Sep 6, 2025
@muellerj
Copy link
Author

muellerj commented Sep 7, 2025

Got it to work, thanks for the pointer. I'll move the descriptions from TEMPLATES.md into their respective ./lib/tilt/*.rb files and get back to you.

@muellerj muellerj reopened this Sep 23, 2025
@muellerj muellerj closed this Sep 23, 2025
@muellerj
Copy link
Author

See #21

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers
No reviews
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
2 participants
@muellerj @jeremyevans