Improve title of Python API pages; low-hanging fruit!

Currently, the Doxygen-generated pages for the Python API produce titles where the project name appears first, followed by the page topic. That results in tabs that look like this image:

When you inevitably open up several topics, the tabs don’t help navigate quickly between the topics.

Much better would be to show only the page topic, or the page topic followed by the project name. This “reverse hierarchy” title pattern is similar to that used by google search results (“searchterm - Google Search”) or page/tab titles when browsing gitlab repos.

For the Python API it would look like this mockup:

Since each tab would show the topic name, you could jump immediately between the topics you need.

That tab text is set by the page’s <title> tag, which in turn is set in a pattern in a template provided to Doxygen.

This should be a very simple change to make, and I hoped to make this request easy on the devs by looking on gitlab to find the particular template that controls this for the Python API doc, and point out the exact line in question. However, I could not determine which file pertains to the Python API docs.

I did find:
https://gitlab.com/kicad/code/kicad/-/blob/master/doxygen/header.html

where there’s the snippet:
<title>$projectname: $title</title>

which could be changed to:

<title>$title - $projectname</title>

… but I’m pretty sure that this is not the header.html that applies to the PCBNew Python API docs.

Regardless, it’s that type of change that would be needed to make this title improvement.

It would be lovely if someone could make this change, or reply with details of where this change should be made and I can file an issue with the fix included.

4 Likes