Let's pretend we have a Rails project with a class named Foo residing in the lib directory.
We want to generate some HTML based on its attributes.
Now, creating a big string by concatenating HTML fragments appropriately doesn't feel right in the least bit.
My question is: is there a blessed way to do it?
You have a couple pretty straightforward options. If you're using ERB, you can do something like:
ERB.new(File.read(the_file_path)).result
I'm using a library called Tilt (https://github.com/rtomayko/tilt) in one of my applications to render a HAML template. Here's the exact sausage factory code that I'm running right now:
template = Tilt.new(ITEM_TEMPLATE) # ITEM_TEMPLATE is the path of a .haml file
template.render nil, {:item => item, :item_details => item_details}
# item and item_details are now available as local variables in the partial
If you don't want to go the templating route, you could try something like Erector (http://erector.rubyforge.org/userguide.html) as well.
Worst case scenario: instead of concatenating fragments, you could use the HEREDOC to format it nicely:
<<-HTML
<div id="foo">
<span class="bar">#{thing.method}</span>
<div>#{thing.attribute}</div>
</div>
HTML
Related
I'm using Docusaurus to publish documentation for an open source library's API. The headings of my source markdown files correspond to the names of methods and properties for classes in the library. This all works fine.
However, the anchors that are created in the HTML are all lowercase. I want them to respect the capitalization used in the markdown file.
For example, this markdown header:
###.doSomething()
Generates the following HTML:
<h3>
<a aria-hidden="true" tabindex="-1" class="..." id="dosomething"></a>.
<code>.doSomething()</code>
<a class="..." href="#dosomething" title="...">#</a>
</h3>
As you can see, camelCase is transformed to lowercase. I would like to keep capitalization intact. Is it possible?
P.S. The markdown files are automatically generated from jsdoc comments. In jsdoc, links to a method or properties include capitalization.
TL;DR
Inside your project, navigate to the directory node_modules > github-slugger;
Open the index.js file;
Remove the line if (!maintainCase) string = string.toLowerCase()
The function will become something like this:
function slugger (string, maintainCase) {
if (typeof string !== 'string') return ''
// if (!maintainCase) string = string.toLowerCase() <-- remove this!
return string.trim()
.replace(specials, '')
.replace(emoji(), '')
.replace(whitespace, '-')
}
IMPORTANT!
If you update the docusaurus, you may need to apply this change again;
It may be necessary to edit the doc to see the changes, because of cache. Here I edited the doc file and it worked;
You must restart the docusaurus service after you make this change. And probably needs to clear the cache with npm cache clear --force;
Also, I think you should delete the folder .docusaurus to force the rebuild of all documents.
RESULT
The .md file:
---
id: intro
---
# Random title
### WriNTinG with CaSeS
test 1
### .doAnotherThink()
test 3
### .doCamelCaseWithSeveralLETTERS()
test 3
ROADMAP
I must say that this one was hard. First I tried to track down the anchor tags, then the description. Eventually I found about the github-slugger, and looked like that was the way.
But once I made the changes, nothing had happened to the document! So after hours trying, I gave up… Then, just for curiosity, I decide to see what the slug function did to the document, by adding a second header with the same name. And — luck! — it kept the original case.
It turns out that you can simply use explicit IDs to solve this issue: https://docusaurus.io/docs/next/markdown-features/headings#explicit-ids
I can't figure out how to get variables into Sphinx documents via a template. I am certainly making an elementary mistake, but while there is lots of documentation for using Jinja/Flask templates for web service and some documentation for Sphinx using it, I am having trouble doing the following. Maybe it's not possible and I'm barking up the wrong tree, but then this is fairly different from how variables work in general in web (as opposed to doc) templates?
I am working within a much larger project. Suppose in my project's conf.py I make a variable, say
LANGS = ['en', 'de', 'cn']
I know that this works because if I do the docbuild (we have a custom docbuild but I don't think it does anything really crazy other than a customized logger and eating a bunch of 'chatter') with the following line in conf.py
print len(LANGS)
it shows up during the docbuild.
But now of course I want to access this variable in my template. As far as I can tell, we override index.rst with templates/index.html, which inherits from the basic layout.html for Sphinx. And if I do
<p>We have {{ LANGS|len }} languages</p>
I get
We have 0 languages
Now, this is weird, because sometimes I can cause an error in the build by referring to variables not defined (though not consistently), so that somehow it 'knows' that the variable is defined but thinks it has length zero. Or does a "null" variable have length zero automatically?
How do I get this variable defined - or is it not possible?
What I want to do is then do something for each language in the list (make an outside link, in particular), but I figure there is no point in trying {% for %}/{% endfor %} or whatever if I can't get this working. Maybe Sphinx implements only a subset of Jinja?
Anyway, please help!
There are at least two ways to pass variables to a template:
Via html_context:
A dictionary of values to pass into the template engine’s context for all pages. Single values can also be put in this dictionary using the -A command-line option of sphinx-build.
Example:
# conf.py:
html_context = {'num_langs': len(LANGS)}
<!-- template: -->
<p>We have {{ num_langs }} languages</p>
Via the html_theme_options. This requires adding an option to theme.conf (you can create a theme by inheriting from a standard one):
[options]
num_langs = 1
Then you can set num_langs in conf.py via html_theme_options:
html_theme_options = {'num_langs': len(LANGS)}
and use it in a template:
<p>We have {{ theme_num_langs }} languages</p>
I would like to know more about the syntax for phpBB, for example the code below :
<div id="site-description">
{SITE_LOGO_IMG}
<h1>{SITENAME}</h1>
<p>{SITE_DESCRIPTION}</p>
<p class="skiplink">{L_SKIP}</p>
</div>
I have 2 questions -
1.) How do the program define the data inside {xxx}?
2.) Where is the files located or what is the file name to define the data inside {xxx}
Thanks for helping.
{L_*} is language syntax and it located in the languages folder.When the tag starts with L_ it recognise it as a language variable, else its recognised as a variable specified from the source.
The template tags {} are defined in includes/template.php
If you have a page named page.php and with defined phpbb in it, you can create own tag and use it on own template.There are global tags in includes/functions.php and private for each file (like in viewtopic.php there is postrow. template prefix).
See http://wiki.phpbb.com/Template.assign_vars for making and using such template tags.
From a single view file containing e.g. LaTeX code with ERB inserts, I would like to be able to:
render to a LaTeX source file, by evaluating the ERB
render to PDF, by compiling the previous result using a custom latex_to_pdf() function
The first case can be achieved by registering a template handler:
ActionView::Template.register_template_handler :latex, LatexSource
where LatexSource is a subclass of ActionView::Template::Handler implementing call(template) or compile(template).
This allows a view file "action.tex.latex" to be accessed and processed correctly as "controller/action.tex".
The second case seems much harder though:
how can the request "controller/action.pdf" be sent to the template handler as if it was "controller/action.tex", and pass the result through latex_to_pdf() before sending the response to the user?
Many thanks
Couldn't you just register another template handler :pdf whose compile method looks similar to this?:
def compile
latex_to_pdf LatexSource.compile(template)
end
Update:
Ok, right, this results in the need of having the view duplicated (action.tex.latex, action.tex.pdf).
Next idea:
respond_to do |format|
format.latex
format.pdf { render :file => latex_to_pdf(render) }
end
As far as I can remember, render returned the rendered template as String in Rails 2.3.
I don't know how it behaves in Rails 3.
You could experiment with render or _render_template. If this works, we could think about how to make this more dry and comfortable for multiple actions.
I didn’t use it myself (yet), but it looks as if https://github.com/jacott/rails-latex could do the job for you.
I am creating internal documentation for a C++ project using Doxygen. I am having Doxygen include the source for methods, etc., but this makes the page kind of hard to scan. I'd like it to behave like rdoc and hide the source in a block that is collapsed by default.
I thought that HTML_DYNAMIC_SECTIONS might let me do this, but alas, the changelog says that option only affects diagrams and graphs.
Maybe I could do it by editing the LAYOUT_FILE?
Anyhow, smart people, how can I coerce Doxygen to generate collapsable code sections?
if includ[ing] the source for methods, etc, [...] makes the page kind of hard to scan, why don't you just link to it (SOURCE_BROWSER = YES) instead of including it (INLINE_SOURCES = YES)? this would make the pages easier to scan and faster to load, and the source would still be accessible (at the expense of one more source page load). depends on how often you actually need to access the source, i guess.
that being said, there is a way to generate collapsible code sections (you will have to modify the source and recompile Doxygen, though):
collapsible sections in Doxygen's HTML output are marked with two nested <div>s like so:
<div class="dynheader"><div class="dynsection">
[collapsible section]
</div></div>
included code sections are marked like so: <div class="fragment"><pre class="fragment">...</pre></div>
thus, to make the included code sections collapsible, you have to either
modify the code that generates the <div class="fragment"><pre class="fragment">...</pre></div> to generate <div class="dynheader"><div class="dynsection">...</div></div> (and probably adjust some css), or
change the javascript initDynSections() function that scans and collapses the collapsible sections to recognize <div class="fragment"><pre class="fragment"> as one of them.
the implementation (or going the SOURCE_BROWSER route :)) is left as an exercise for the reader. good luck!
oh, and if you should succeed with a patch, it would be great if you could submit it to dimitri so that he can include it in a future version. thanks!
coming along here using the search engine of my choice i just want to leave a note here that it is not absolutely necessary to modify any doxygen source.
When this question was asked there was probably no possibility to embed pure html using the htmlonly tag but with this in mind one is able to create foldable container sections abusing a function named toggleVisibility
function toggleVisibility(linkObj)
{
var base = $(linkObj).attr('id');
var summary = $('#'+base+'-summary');
var content = $('#'+base+'-content');
var trigger = $('#'+base+'-trigger');
var src=$(trigger).attr('src');
if (content.is(':visible')===true) {
content.hide();
summary.show();
$(linkObj).addClass('closed').removeClass('opened');
$(trigger).attr('src',src.substring(0,src.length-8)+'closed.png');
} else {
content.show();
summary.hide();
$(linkObj).removeClass('closed').addClass('opened');
$(trigger).attr('src',src.substring(0,src.length-10)+'open.png');
}
return false;
}
that is currently available every time the documentation is generated in a file called dynsections.js placed in the documentation root.
Regarding this code one gets to know the conditions to be able to create foldable code from his/her own documentation using Javascript avoiding inner execution faults in this function and preventing further javascript code from being uninterpreted.
dom element with a unique identifier id
another encapsulated dom element with unique identifier id-summary
another encapsulated dom element with unique identifier id-content
another encapsulated dom element with unique identifier id-trigger
the id-trigger element must contain a src attribute with at least 1 character
the class attributes of the main containers do not matter
With theese conditions in mind one can create the following code.
## Fold me
## <div id="example-div">
## <div id="example-div-summary"></div>
## <div id="example-div-content">
## <pre>
## foo
## bar
## </pre>
## </div>
## <div id="example-div-trigger" src="-"></div>
## </div>
## #htmlonly <script type="text/javascript">$("#example-div").ready(function() { toggleVisibility($("#example-div")); });</script> #endhtmlonly
The doxygen code above is used to document bash code using bash-doxygen so it might look a bit different from pure doxygen code. The first part involving the div containers is already described mentioning the conditions to fit the source of the function toggleVisibility and make it executable without any errors adjusting the doxygen comments for our needs.
The unique id prefix used in here is example-div. In line one there is a hyperref link setup to unfold a section using javascript directly in conjunction with some jQuery code.
What's left is the one liner at the end. It contains the jQuery script need to be run to initially fold the specific segment. For the bash-doxygen (and probably other languages) the block needs to be a one liner because of the script's block scope
Normally the contents between \htmlonly and \endhtmlonly is inserted as-is. When you want to insert a HTML fragment that has block scope like a table or list which should appear outside <p>..</p>, this can lead to invalid HTML. You can use \htmlonly[block] to make doxygen end the current paragraph and restart it after \endhtmlonly.
as noticed in the doxygen documentation and a comment below the right marked solution of the stackoverflow answer on including script tags in doxygen documentations.
Thank you for reading.
Hope this helps some people that come along here.