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>
Related
I have a generic test and need it to be always saved under a particular name for the given table it is running on, e.g. on table report_revenue the generated generic test name will always be diff_check_report_revenue. Right now the default dbt naming behavior for generic tests is kinda messy (it sets the test name based on the test config, which is a great idea for most cases, but unfortunately not for my particular one).
According to the docs it looks like the [alias]https://docs.getdbt.com/reference/resource-configs/alias is exactly what I need. However, I also need to set the name dynamically based on the table that is tested. I know it can be set in the yml config by setting the field alias, but I hope there might be a more elegant solution.
When I try the following:
{{
config({
"severity": 'warn',
"tags": ["diff_check"],
"alias": 'diff_check_' + {{ model | replace("XXXXXXX") | trim }}
})
}}
It just doesn't work and dbt completely ignores the alias property. model is the relation on which the test is running. It's probably just my own wrong syntax, but I'm stuck and humbly asking for advice. Thanks a lot in advance!
The docs are super confusing on test config, since they group together generic tests and singular tests, and the behavior is different.
You can use a config() block inside the definition for a generic test to configure it, and some keys (e.g., severity) work fine, but alias is not one of them.
I think alias is meant for singular tests only. To give generic tests a unique identifier (only possible since v1.1), you are supposed to use the name property (not config). Docs. Does this make sense? No. Does it make it easy for you to do what you want to do? Also no.
I'll point out that the default naming convention for a generic test includes the name of the test followed by the name of the model, but assuming that isn't good enough, your only option will be to add a name property to every test, where you define the test in the properties (fka schema.yml) file. And it looks like the name property doesn't jinja-template its value (so you can't use jinja to populate the test name). So you'll have to do a lot of this:
models:
- name: my_model
tests:
- diff_check:
name: diff_check_my_model
You could fork dbt-core. The relevant code is here.
I'm trying to have a structure to run a dbt project, where I have multiple entities (bank, names, cars). I'm going to have exactly the same code for them all.
Based on that, I'm trying to have several folder with the same code, where I can define inside the dbt_project.yamlfile. The idea is something like this:
vars:
db_name: 'db_official'
staging:
bank: 'variable_bank'
car: 'variable_car'
name: 'variable_name'
The variable "db_name" works. So, my the two problems I'm having are:
How to have this structure inside the the yaml file?
How to reference this structure inside each file?
(extra) Any other ideas how to handle this?
Thanks!
vars are basically globals. They can be scoped to your whole project, or to a package within your project, but not more specifically than that (they share a flat namespace). See the docs.
I would pull out the common code into a macro, then call that macro from each model file, passing in the unique values as string literals in the model file:
-- models/staging/bank.sql
{{ my_model_template('variable_bank') }}
-- models/staging/car.sql
{{ my_model_template('variable_car') }}
I am developing a Shopify Theme. The structure I have now is (excerpt):
Snippets
custom-message-snippet
Sections
custom-message-section
welcome-page-a-section
welcome-page-b-section
Templates
welcome-page-a-template
welcome-page-b-template
...
Custom message snippet uses settings that are in the custom-message-section, that is:
a) message
b) header text
I'd like for users to be able to add custom-message-snippet to welcome-page-a and welcome-page-b in a way that settings for both are different.
I can not render section 'custom-message-section" inside welcome pages because it is not possible (and a workaround is nasty).
There are fifty welcome pages. Every welcome page is totally different.
My question is:
How to allow users to use custom-message-snippet in all welcome pages without copying and pasting custom-message-page setting schema to each and every welcome page?
combine custom-message-section to custom-message-snippet
combine welcome-page-\w+-template to welcome-page-template, you only need to have one template and schema set, the user will control the sections in schema selection.
in template, use schema to select the page-content; this, defined by a bunch of if-else /switch statement.
{% section "welcome-page-custom-message-section" %}
{% section "welcome-page-content" %}
in welcome-page-custom-message-section
{% render "custom-message-snippet" with "string from welcome-page-section schema " %}
create checkbox select schema for custom message to appear or not.
Short: You can't.
Long: Using storefront 2.0, you end you having blocks, which can be added manually to any template.
It is possible if you have a little knowledge of Node.js and you're using the Shopify CLI.
Check the solution here: Shopify Section / Block Schema In A Separate File. It is possible
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}!
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.