More/custom hierarchy in html left navigation bar

[ogallagher]

The current default layout for the generated html pages includes an index/navigation bar along the left side, organized like so:

• Super-module
• Sub-modules
• Global variables
• Functions
• Classes
  • ClassOne
    • apple
    • banana
    • cherry
    • dolphin
    • ...
  • ClassTwo
    • apple
    • ....
  • ...

I would much prefer that within each class, the members be better organized (and also collapsible), much like how they’re organized in the main section of the page:

• Classes
  • ClassOne
    • Ancestors
    • Descendants
    • Class variables
    • Class methods
    • Instance variables
    • Instance methods
  • ...

How do I add a custom template with a different file path to be used instead of pdoc/templates/html.mako? In the documentation for Module.html(self, minify=True, **kwargs) --> str I’m not seeing an indication that this is possible.

[kernc]

Rendering to HTML always takes html.mako template, but you can influence the directory where html.mako is sought (programatically) by amending pdoc.tpl_lookup: https://github.com/pdoc3/pdoc/blob/72e41dbf91646a39bc900ca6f875e5f75660e6a4/pdoc/__init__.py#L54-L66 or (CLI) via --template-dir: https://github.com/pdoc3/pdoc/blob/72e41dbf91646a39bc900ca6f875e5f75660e6a4/pdoc/cli.py#L105-L112

Curious to see what you end up with! :eyes:

[ogallagher]

@kernc Thank you! I’ll attempt amending pdoc.tpl_lookup.directories and will see how it goes.

[ogallagher]

I’ve managed to, at least in terms of utility, achieve what I was looking for. After inserting my custom template directory as the first element in pdoc.tpl_lookup.directories, I then copied the default mako template files into the new location and made some modifications. I only extracted key snippets in part due to the required secrecy of the project involved, but others interested in customizing the generated html output from pdoc could use this as an example:

css.mako

```mako <%def name="myproject_css()" filter="minify_css"> ## ogallagher 2021-02-25 myproject custom css rules .myproject-collapsee { display: none; } .myproject-collapsee.show { display: block; } .myproject-collapser { display: inline; padding-left: 8px; padding-right: 8px; } .myproject-collapser:hover { font-weight: bold; cursor: pointer; } ```

html.mako

```mako ## ogallagher custom html char aliases for legibility <% alias_to_html_char = { 'triangle-solid-right': '►', 'triangle-solid-right-small': '▸', 'triangle-solid-down': '▼', 'triangle-solid-down-small': '▾', 'arrow-down-to-bar': '⤓', 'arrow-up-to-bar': '⤒' } %> ## ... ## ogallagher customized so

can be collapsible <%def name="show_column_list(items, name=None)"> <% two_column = len(items) >= 6 and all(len(i.name) < 20 for i in items) %>
% for item in items:
• ${link(item, item.name)}
% endfor
## ... ## ogallagher section collapse controller <%def name="myproject_collapser(collapsee_id)">
${alias_to_html_char['triangle-solid-right-small']}
## ... <%def name="myproject_index_collapse_js()"> ## ... <%def name="module_index(module)"> ## custom module index column (collapsible headers) ## ...
<%include file="logo.mako"/> ## ...
Index
${extract_toc(module.docstring) if extract_module_toc_into_sidebar else ''}
% if supermodule:

• Super-module

  • ${link(supermodule)}
% endif % if submodules:

• Sub-modules ${myproject_collapser('submodules')}

  % for m in submodules:
  • ${link(m)}
  % endfor
% endif % if variables:

• Global variables ${myproject_collapser('variables')}

  ${show_column_list(variables, 'variables')}
% endif % if functions:

• Functions ${myproject_collapser('functions')}

  ${show_column_list(functions, 'functions')}
% endif % if classes:

• Classes ${myproject_collapser('classes')}

  % for c in classes:

  • ${link(c)} ${myproject_collapser(c.qualname)}

    <%doc> <% members = c.functions(sort=sort_identifiers) + c.methods(sort=sort_identifiers) if list_class_variables_in_index: members += ( c.instance_variables(sort=sort_identifiers) + c.class_variables(sort=sort_identifiers) ) if not show_inherited_members: members = [i for i in members if not i.inherits] if sort_identifiers: members = sorted(members) %> % if members: ${show_column_list(members)} % endif
    <% c_ancestors = c.mro() c_subclasses = c.subclasses() c_class_variables = c.class_variables(show_inherited_members, sort=sort_identifiers) c_class_methods = c.functions(show_inherited_members, sort=sort_identifiers) c_inst_variables = c.instance_variables(show_inherited_members, sort=sort_identifiers) c_inst_methods = c.methods(show_inherited_members, sort=sort_identifiers) c_collapser_prefix = c.qualname %> ## ancestors % if c_ancestors: <% collapsee_id = '{}-ancestors'.format(c_collapser_prefix) %>
    • Ancestors ${myproject_collapser(collapsee_id)}
      % for cls in c_ancestors:
      • ${link(cls)}
      % endfor
    %endif ## subclasses % if c_subclasses: <% collapsee_id = '{}-subclasses'.format(c_collapser_prefix) %>
    • Subclasses ${myproject_collapser(collapsee_id)}
      % for sub in c_subclasses:
      • ${link(sub)}
      % endfor
    % endif ## class vars % if c_class_variables: <% collapsee_id = '{}-class-vars'.format(c_collapser_prefix) %>
    • Class vars ${myproject_collapser(collapsee_id)}
      % for v in c_class_variables:
      • ${link(v, v.name)}
      % endfor
    % endif ## class methods % if c_class_methods: <% collapsee_id = '{}-class-methods'.format(c_collapser_prefix) %>
    • Class methods ${myproject_collapser(collapsee_id)}
      % for f in c_class_methods:
      • ${link(f, f.name)}
      % endfor
    % endif ## instance vars % if c_inst_variables: <% collapsee_id = '{}-inst-vars'.format(c_collapser_prefix) %>
    • Instance vars ${myproject_collapser(collapsee_id)}
      % for v in c_inst_variables:
      • ${link(v, v.name)}
      % endfor
    % endif ## instance methods % if c_inst_methods: <% collapsee_id = '{}-inst-methods'.format(c_collapser_prefix) %>
    • Instance Methods ${myproject_collapser(collapsee_id)}
      % for f in c_inst_methods:
      • ${link(f, f.name)}
      % endfor
    % endif ## inherited % if not show_inherited_members: <% members = c.inherited_members() %> % if members:
    • Inherited ${myproject_collapser('{}-inherited'.format(c_collapser_prefix))}
      % for cls, mems in members:
      • ${link(cls)}:
        % for m in mems:
        • ${link(m, name=m.name)}
        % endfor
      % endfor
    % endif % endif
  % endfor
% endif
## ... ## ... <%namespace name="css" file="css.mako" /> ## ...
% if module_list:
${show_module_list(modules)}
% else:
${show_module(module)}
${module_index(module)} % endif
## ... ${myproject_index_collapse_js()} ```

Here's what my result looks like:

Notably I forgot to sort members alphabetically within each class member, but that should be trivial compared to what’s done already.

[DOSull]

It would be great if this behaviour could be added as an option to pdoc. My JS/CSS/HTML isn't good enough to pick up the posted files and just use them in my project, unfortunately!