sphinx-doc/sphinx

Improve support for pages without sections (titles)

Open

#8,356 opened on Nov 1, 2020

View on GitHub
 (4 comments) (2 reactions) (0 assignees)Python (1,985 forks)batch import
help wantedinternals:toctreetype:enhancement

Repository metrics

Stars
 (5,625 stars)
PR merge metrics
 (Avg merge 10d 11h) (11 merged PRs in 30d)

Description

Is your feature request related to a problem? Please describe. Pages that don't have any section seems to be hard to work with. Also, their HTML <title> looks odd (in the browser tabs for example). Currently, a page that doesn't have any section (with for example html_title set to 'test') will render <no title> — test.

Also it seems like the document can't be included in any toctree, even explicitly (using Title <test_doc>).

Describe the solution you'd like

  • Ability to remove the <no title> — part so my page title is equal to html_title (for example in conf.py).
  • Allow to explicitly reference documents that have no sections in a toctree.

Describe alternatives you've considered I've tried patching it manually, without great success.

Contributor guide

Research direction
Investigate how Sphinx handles pages without sections and how to modify the title rendering and toctree inclusion. Look into the theme and configuration options to allow customizing the title display.
Tech stack
python
Domain
documentation
Issue type
Feature
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
3
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
Half day
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
Active
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
Clear
Prerequisites
PythonSphinx
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
60