I want to include image in yard-genereted documentation, but can't find anywhere how to do this... Does anyone know how to do this?
You can just add <img /> tag to your documentation:
# Blah-blah
#
# <img src=img/1.png />
# #param [String] blah
# #return [String] blah
def foo(bar)
end
Use rdoc-image: links:
# Gets foo.
#
# rdoc-image:img/1.png
def foo(bar)
"foo"
end
is rendered by YARD into
<p>Gets foo.</p>
<p><img src="img/1.png"></p>
The rdoc-images: also works in standalone *.rdoc files.
Depending on your markup format you may have to use another mechanism. For instance, if you use Markdown, the syntax is . In RDoc, an img tag should work, but you can check if they have added a special markup syntax for this. Note that RDoc probably (not sure) doesn't like XHTML, you should use with no ending /.
Related
I am using Ruby's RDiscount to convert markdown to HTML.
The markdown documents contain links (or images) that are relative to the path of the markdown file itself.
Is there a way for me to tell RDiscount that it should prepend all relative links with a string (folder) of my choice?
I am trying to achieve an effect similar to how GitHub shows images in README - where the files are looked for in the same directory as the README.
Here is an example code:
require 'rdiscount'
markdown = "\n\n[link](somewhere.html)"
doc = RDiscount.new(markdown)
# I would like to do something here, like:
# doc.base_link_path = 'SOMEFOLDER'
html = doc.to_html
puts html
# actual output =>
# <p><img src="image.png" alt="pic" /></p>
# <p>link</p>"
# desired output =>
# <p><img src="SOMEFOLDER/image.png" alt="pic" /></p>
# <p>link</p>"
I looked at the RDiscount class documentation but did not find anything like this.
Most languages allow block comments, and multiline commands.
For example, a multiline comment in HTML looks like the following:
<!--
Warning, brave programmer:
Here be dragons.
-->
In Elixir, the closest thing I have found comes from EEx (docs).
EEx smartengine <% #comments %> seem to be discarded from source, even if they are multiline. However, this is just a workaround.
Does Elixir have a multiline comment feature, or a way to instruct the compiler to discard text from the compiled .beam file?
Elixir does not have multiline comments.
However, one very common use case for multiline comments is documenting modules and functions, for which you can use the module attributes #doc and #moduledoc together with heredocs.
defmodule MyModule do
#moduledoc """
This module is great at X
"""
#doc """
Frobnicates the given string.
"""
def frobnicate(s) do
end
end
I try to just use """ to quickly comment code a la Python, without turning it into a documentation
"""
def some_function() do
some_code
end
"""
Macros could help here to some degree:
defmodule Comment do
defmacro comment(_text) do
end
end
defmodule TestComment do
import Comment
comment """
Module
Comment
"""
def func do
comment """
Function
Comment
"""
end
end
You can simply use module attributes for multiline comments, no macro required. I typically use the following for documenting/commenting private functions:
#docp """
This is my
multi line
comment
"""
Background
I'm trying to test the formatting of some HAML templates outside of Rails. The idea is to pass in some instance variables on the command line or via an included Ruby file, rendering the template to standard output. I tried this several different ways without success, as outlined below.
Requiring a Ruby File
For example, given the following two files:
HAML template: "test.haml"
!!!
%h1 Testing HAML CLI
%p= #bar
%p= #baz
Ruby file: "test.rb"
#foo = 'abc'
#bar = '123'
I would expect an invocation like haml -r ./test test.haml to return an interpolated HTML file on standard output, but it doesn't. Instead, I get just the HTML:
<!DOCTYPE html>
<h1>Testing HAML CLI</h1>
<p></p>
<p></p>
Programmatic Attempt
Since this didn't work, I also tried to do this programmatically. For example:
#!/usr/bin/env ruby
require 'haml'
#foo = 'abc'
#bar = '123'
engine = Haml::Engine.new(File.read 'test.haml')
puts engine.render
with exactly the same results, e.g. just the HTML with no variable interpolation.
Restating the Question
Clearly, something else is needed to get HAML to render the template with its associated variables. I would prefer to do this from the command line, either by passing arguments or including a file. How should I be invoking HAML from the command line to make it happen?
If that's not possible for whatever reason, how should I invoke HAML programmatically to perform the interpolation without depending on Rails?
You can supply a scope object and a local variables hash to the render method. In your example case, you would call:
engine = Haml::Engine.new(File.read 'test.haml')
engine.render(Object.new, { :#foo => 'abc', :#bar => '123' })
The reason that both of these examples are not working is that you are attempting to access instance variables from a different class. The simplest solution is to define and use methods instead of attempting to access another classes instance variables as if they were your own.
I.E. in test.rb
def foo
'abc'
end
test.haml
!!!
%h1 Testing HAML CLI
%p= foo
In order to keep some of my Jekyll sites simple, I'm always using the same layout. That is to say, I'm always writing something like. . .
---
layout: default
title: Here's my Title
---
. . . as the YAML Front Matter at the top of my pages.
What I'd rather write, however is only. . .
---
title: Here's my Title
---
. . . and have Jekyll assume that it should use a certain layout, as if I had explicitly written "layout: default" (or whatever), as above.
I don't see a way to specify this behavior in _config.yml. Maybe I could write a Jekyll plugin that would allow this. . . any ideas?
This can be done using Frontmatter defaults:
defaults:
-
scope:
path: "" # empty string for all files
values:
layout: "default"
This setting is available since Jekyll Version 2.0.0.
Shorter and with no monkey-patching:
# _plugins/implicit_layout.rb
module ImplicitLayout
def read_yaml(*args)
super
self.data['layout'] ||= 'post'
end
end
Jekyll::Post.send(:include, ImplicitLayout)
Caveat: GH Pages won't run your plugins.
Here's a Jekyll plugin you can drop in as _plugins/implicit-layout.rb, for example:
# By specifying an implicit layout here, you do not need to
# write, for example "layout: default" at the top of each of
# your posts and pages (i.e. in the "YAML Front Matter")
#
# Please note that you should only use this plugin if you
# plan to use the same layout for all your posts and pages.
# To use the plugin, just drop this file in _plugins, calling it
# _plugins/implicit-layout.rb, for example
IMPLICIT_LAYOUT = 'default'
module Jekyll
module Convertible
def read_yaml(base, name)
self.content = File.read(File.join(base, name))
if self.content =~ /^(---\s*\n.*?\n?)^(---\s*$\n?)/m
self.content = $POSTMATCH
begin
self.data = YAML.load($1)
self.data["layout"] = IMPLICIT_LAYOUT
rescue => e
puts "YAML Exception reading #{name}: #{e.message}"
end
end
self.data ||= {}
end
end
end
From hanging out on #jekyll on freenode, I'm given to understand this is a monkey patch.
As Alan W. Smith commented, being able to put "layout: default" in _config.yml would be a nice improvement to this plugin.
Ideally (from my perspective), this functionality could be incorporated in Jekyll itself so a plugin wouldn't be necessary.
By default, you can't do this. Jekyll needs the YAML to specify layout so it knows where to drop it in at.
There are plenty of coloring libraries: colored, term-ansicolor.
But is there any which can do this:
puts "#{'hello'.red} world!".bold
And world! should be bold.
To make it clear, I want to get this:
"\e[1m\e[31mhello\e[0m\e[1m world!\e[0m"
or better even this (just shorter):
"\e[1;31mhello\e[0;1m world!\e[0m"
instead of this:
"\e[1m\e[31mhello\e[0m world!\e[0m"
As there is none, I wrote my own, with blackjack and hookers smart one — smart_colored
gem install smart_colored
and run
require 'smart_colored/extend'
# without extend you'll need to use 'string'.colored.red
puts "#{'hello'.red} world!".bold
The lib is called Highline
It has a color method: say("This should be <%= color('bold', BOLD) %>!")
Which can be easily used to implement String#bold.
In case you are using highline I made a gem that extends colors and provides helpers such as:
say_bold 'this is bold text'
https://github.com/bonzofenix/highline-color