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

How to modify pages titles? #79

Open
cglacet opened this issue Oct 26, 2020 · 11 comments
Open

How to modify pages titles? #79

cglacet opened this issue Oct 26, 2020 · 11 comments

Comments

@cglacet
Copy link

cglacet commented Oct 26, 2020

I'm trying to modify a page title without having an <h1> tag in my page. Is it possible?

The current behaviour when setting html_title = 'test' is to output <no title> test. I would for example like to remove the <no title> part so my page title is equal to html_title. Do I need to create a template for that?

@bashtage
Copy link
Owner

Can you be a bit more specific? In particular, can you posted the relevant parts of your conf and the rst page?

@cglacet
Copy link
Author

cglacet commented Oct 27, 2020

Hmm, I'm not sure I get what you mean, but here is my a test.rst file:

file without header/title.

And here are the relevant parts of the config.py:

import sphinx_material

project = 'Kune'
release = '0.1'

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.viewcode',
    'sphinx_copybutton',
]

html_sidebars = {
    "**": ["logo-text.html", "globaltoc.html", "localtoc.html", "searchbox.html"]
}

extensions.append("sphinx_material")
html_theme_path = sphinx_material.html_theme_path()
html_context = sphinx_material.get_html_context()
html_theme = "sphinx_material"

html_theme_options = {
    'nav_title': 'Kune servers documentation',
    'globaltoc_depth': 3,
    'globaltoc_collapse': True,
    'globaltoc_includehidden': True,
}

Using this configuration, the resulting HTML tag is <title>&lt;no title&gt; — Kune 0.1 documentation</title>.

I would like to know how to make the resulting tag <title>Kune 0.1 documentation</title> or any other title I could decide to be the default title for no-headings-pages.

EDIT, also, I guess you already know that, if I set html_title = "Another title" I'll get <title>&lt;no title&gt; — Another title</title> which doesn't solve the "<no title>" problem.

@bashtage
Copy link
Owner

bashtage commented Nov 1, 2020

This seems to be Sphinx's default for a page with no title. This "title" (<no title>) is then passed to the template engine which is then rendered in place fo the title.

This could be addressed here, but it may not be the right place for a fix. Sphinx might be the right place to have an option to override the default value of <no title> to be an empty string.

Normally the title is read from the pages top heading.

@bashtage
Copy link
Owner

bashtage commented Nov 1, 2020

https://github.com/sphinx-doc/sphinx/blob/af62fa61e6cbd88d0798963211e73e5ba0d55e6d/sphinx/environment/collectors/title.py#L53

Does not seem to provide a method to override.

@cglacet
Copy link
Author

cglacet commented Nov 1, 2020

Thanks, I'll move this to sphinx then and patch it on my side in the mean time.

@bashtage
Copy link
Owner

bashtage commented Nov 1, 2020

Great. I'd rather not try and fitis here since it would be pretty hacky, something along the lines of

if title =! "<no title>":
    full_title = title + " - ' + html_title

which is very dependent on how sphinx renders "no title". I would suggest that Sphinx could add an enhancement for conf.py that would be something like include_empty_page_title which would be True or False. Alternatively, it could just have a default page title, e.g., default_page_title = "" which would then be reasonable to filter for so that title would only be added when not-empty.

@bashtage bashtage closed this as completed Nov 1, 2020
@cglacet
Copy link
Author

cglacet commented Nov 1, 2020

That patch is not enough sadly, there is another place that treats title apparently.

Here is how I patched it (at least to remove the <no title> part), in my conf.py:

from docutils import nodes
from sphinx.application import Sphinx
from sphinx.environment.collectors.title import TitleCollector

_process_doc = TitleCollector.process_doc

def process_doc(self, app: Sphinx, doctree: nodes.document) -> None:
    if doctree.traverse(nodes.section):
        _process_doc(self, app, doctree)
    else:
        titlenode = nodes.title()
        app.env.titles[app.env.docname] = titlenode
        app.env.longtitles[app.env.docname] = titlenode

TitleCollectorprocess_doc = process_doc

This renders — test, for now I can't get rid of the .

Another problem is that, even with setting a title manually in the toctree: A test .rst without any section <test>, the entry doesn't show.

@bashtage
Copy link
Owner

bashtage commented Nov 1, 2020

The - removal would need to come from sphinx-material. If title is empty, then the page title should be html_title if present, and it not, nothing (which might not be 100% compliant in HTML).

@cglacet
Copy link
Author

cglacet commented Nov 1, 2020

The title wouldn't be empty, it would be equal to html_title. Here the problem is that it's equal to f"— {html_title}".

@bashtage
Copy link
Owner

bashtage commented Nov 1, 2020

That is what I mean. One challenge is that html_title has been escaped before it get to templating and the - has been manually inserted, and so some string parsing is needed. Not the end of the world, but starting to feel fragile. This hardcoded behaviour is a misfeature of Sphinx IMO.

@bashtage
Copy link
Owner

bashtage commented Nov 1, 2020

There is a start in#81. It will need to become opt-in before it can be merged.

@bashtage bashtage reopened this Nov 1, 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

No branches or pull requests

2 participants