Skip to content
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.

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

Docs for user templates #1739

Merged
merged 5 commits into from Jun 29, 2020

Conversation

jgsogo
Copy link
Member

@jgsogo jgsogo commented Jun 12, 2020

conan-io/conan#7176

⚠️ Not sure if this is the best place for this section

  • I need to remove things related to conan new, it was just an idea

I like how the commands are listed inline:

...but not in the index:

@jgsogo jgsogo marked this pull request as ready for review Jun 12, 2020
@jgsogo jgsogo requested a review from danimtb Jun 12, 2020
@jgsogo jgsogo added this to the 1.27 milestone Jun 12, 2020
These files should be valid Jinja2 templates and they will be feed with the following
context:

* ``base_template_path``: path to the directory where the choosen template file is
Copy link
Collaborator

@SSE4 SSE4 Jun 16, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

is it required to be absolute path, or can be relative (to what?)

Copy link
Member Author

@jgsogo jgsogo Jun 17, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This variable is provided by Conan. It is the absolute path to the template file.

When the user overrides the default template (which is in-memory, not a file) this variable base_template_path will be equal to <cache>/templates/output (<cache> is the actual path to the cache folder) so the user can use it to provide a path to assets: something like this in the template {{ base_template_path }}/css/myfile.css which will be rendered as the absolute path <cache>/templates/output/css/myfile.css and it will work regardless of the folder where the generated file is located.

For the template provided by Conan by default this will be equal to None, the default template is not a file, it is in-memory.


When the output is a table, the first thing needed are the headers, these can be a sinle row
or two rows like the image above. In order to get the headers you should use
``results.get_headers(keys)`` with a list of extra ``keys`` you want to include. Conan will
Copy link
Collaborator

@SSE4 SSE4 Jun 16, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

it's not obvious here where should I use results.get_headers, in conanfile or somewhere else? I guess link to the reference would be nice here

Copy link
Member Author

@jgsogo jgsogo Jun 17, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This file is the reference for these classes/methods/variables. I'll add "see example below" here, it can help with user expectations.

</tr>
</thead>

* two-rows headers: it returns a list of tuples like the following one:
Copy link
Collaborator

@SSE4 SSE4 Jun 16, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am not sure I follow. list of tuples is python object, right? but template logic seems to be called inside the html file. do you mean this will result in tempalte preprocessor inserting string representation of the list of tuples here?

Copy link
Member Author

@jgsogo jgsogo Jun 17, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In Jinja2 templates the variables are python objects, not just strings. As such python objects you can execute methods on them. In the example above a line was missing, it should be:

        <thead>
            <tr>
                {%- set headers = results.get_headers(keys=['remote', 'package_id']) %}
                {%- for header in headers.row(n_rows=1) %}
                <th>{{ header }}</th>
                {%- endfor %}
            </tr>
        </thead>

Here headers is an object, headers.row(n_rows=1) returns an actual iterable and inside the template you iterate the items as you would do in Python itself (lot of Jinja2 syntax sugar here, but it is like python itself).

Copy link
Member Author

@jgsogo jgsogo Jun 17, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I know this two-rows header thing is not the easiest thing, neither the HTML code to compose the headers of the table from this python object (see all those loops, colspan, rowspan,...)

<cache>/templates/output/info_graph.html


Our template will we the *info_graph.html* file, and it will use the assets from the
Copy link
Collaborator

@SSE4 SSE4 Jun 16, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

not sure if it's fair to advice usage of html extension for the template file. I think something like tmpl (or html.tmpl) would better illustrate the purpose of the file. it's not an HTML and couldn't be properly rendered via web-browser, thus it shouldn't have an html extension IM.

Copy link
Member Author

@jgsogo jgsogo Jun 17, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I often find myself using other extensions, but then I come back to .html for two reasons:

  • Django itself uses .html for the HTML templates. Django is a big Python project and whenever I have doubts I usually follow their convention.
  • Even if it is a template, it will contain HTML tags and code and the IDE will render it with colors and help with code completion.

IMO I'll keep using .html as the suggestion.

SSE4
SSE4 approved these changes Jun 18, 2020
@jgsogo jgsogo merged commit e930b0c into conan-io:develop Jun 29, 2020
2 checks passed
@jgsogo jgsogo deleted the docs/7176-user-provided-templates branch Jun 29, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

4 participants