After some time I spent staring at the jbake code, I figured out that if I declare my own property in jbake.properties :
...
foo=bar
...
I can reuse that in files that go through a template engine by referencing it as ${config.foo}. I'd like to have this substitution working also on the content lvl, i.e. for files written in asciidoc, living inside the content directory.
Is there any non-trivial way to achieve it? How can I make the templating engine to proccess the result of asciidoc parses engine, or make it running it before the asciidoctor?
I found the answer myself.
To use the property substitution in asciidoc files, add following to the jbake.properties:
...
asciidoctor.attributes.export=true
foo=world
...
and reference the variable in aFile.adoc this way:
Hello {foo}!
Related
I faced with the problem of writing my vcs current branch name each time I have written 'todo' comment.
Recently I learned about Intellij's 'Live Templates' which is quite comfortable to use. I tried to apply it to my problem but there's no templates to take out a branch name.
So the question is could I actually take out the name of my branch to code comments somehow?
It is possible to use the groovyScript predefined function and a script to extract the branch name. For example create the following live template:
$COMMENT$ todo [$BRANCH$]: $END$
with abbreviation "todo" and description "Inserts todo comment with branch name". Click Edit variables and give the variables the following definitions:
COMMENT:
lineCommentStart()
BRANCH (updated for 2020.2 and newer)
groovyScript("com.intellij.dvcs.repo.VcsRepositoryManager.getInstance(_editor.project).getRepositoryForFileQuick(com.intellij.openapi.fileEditor.FileDocumentManager.getInstance().getFile(_editor.document)).getCurrentBranchName()")
Skip if defined checked for both variables. The Groovy script is (unfortunately) all one line. Set applicable contexts to Everywhere.
With this live template it is now possible to type todoTab somewhere in a source file and a line comment with the branch name will be inserted. This will insert the proper line comment depending on the language of the file, or nothing in case of languages without a line comment like HTML. And should extract the branch name no matter the type of version control used (I tested with Git).
For live templates you can use predefined functions. Unfortunately there is no function to detect the current VCS branch.
But you can create a template to make work a little easier:
// TODO [$branch_name$]: $comment$
With this template, you still have to fill branch name, but you should not type symbols like [ and caret will be placed automatically.
You can also create a feature request for a new predefined function.
I have a content directory called foo and I want all files under that directory to have an extra metadata item foovar: default, unless explicitly overridden in the file header. I think I'm supposed to do this with EXTRA_PATH_METADATA, but I can't figure out what incantation it wants.
(for my current use case I'm trying to apply template: sometemplate within this dir, but I'm interested in solving the general case as it would make several related headaches go away)
I think what you're looking for is actually DEFAULT_METADATA. Check out this portion of the documentation:
DEFAULT_METADATA = {}
The default metadata you want to use for all articles and pages.
So, in your case it might look something like this in your config file:
DEFAULT_METADATA = {'foovar': 'default'}
Then to assign your custom template(s), see this portion of the documentation.
This wasn't possible at the time I asked. I've since sent the devs a PR adding support, and it's been merged to master. Presumably it will go out in the next release. It makes EXTRA_PATH_METADATA recursive, so you can apply settings to a subdir like this:
EXTRA_PATH_METADATA = {'dirname/subdir': {'status': 'hidden'}}
In my project Mockito.times(1) is often used when verifying mocks:
verify(mock, times(1)).call();
This is redundant since Mockito uses implicit times(1) for verify(Object), thus the following code does exactly what the code above does:
verify(mock).call();
So I'm going to write an a structural search drive inspection to report such cases (let's say, named something like Mockito.times(1) is redundant). As I'm not an expert in IntelliJ IDEA structural search, my first attempt was:
Mockito.times(1)
Obviously, this is not a good seach template because it ignores the call-site. Let's say, I find it useful for the following code and I would not like the inspection to trigger:
VerificationMode times = Mockito.times(1);
// ^ unwanted "Mockito.times(1) is redundant"
So now I would like to define the context where I would like the inspection to trigger. Now the inspection search template becomes:
Mockito.verify($mock$, Mockito.times(1))
Great! Now code like verify(mock, times(1)).call() is reported fine (if times was statically imported from org.mockito.Mockito). But there is also one thing. Mockito.times actually comes from its VerificationModeFactory class where such verification modes are grouped, so the following line is ignored by the inspection:
verify(mockSupplier, VerificationModeFactory.times(1)).get();
My another attempt to fix this one was something like:
Mockito.verify($mock$, $times$(1))
where:
$mock$ is still a default template variable;
$times$ is a variable with Text/regexp set to times, Whole words only and Value is read are set to true, and Expression type (regexp) is set to (Times|VerificationMode) -- at least this is the way I believed it should work.
Can't make it work. Why is Times also included to the regexp? This is the real implementation of *.times(int), so, ideally, the following line should be reported too:
verify(mockSupplier, new Times(1)).get();
Of course, I could create all three inspection templates, but is it possible to create such a template using single search template and what am I missing when configuring the $times$ variable?
(I'm using IntelliJ IDEA Community Edition 2016.1.1)
Try the following search query:
Mockito.verify($mock$, $Qualifier$.times(1))
With $Qualifier$ text/regexp VerificationModeFactory|Mockito and occurrences count 0,1 (to find it when statically imported also).
To also match new Times(1) you can use the following query:
Mockito.verify($mock$, $times$)
With $times$ text/regexp .*times\s*\(\s*1\s*\) and uncheck the Case sensitive checkbox.
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 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.