Skip to content

🐛 fix(docs): resolve multiple manpage issues#3881

Merged
gaborbernat merged 2 commits intotox-dev:mainfrom
gaborbernat:3878
Mar 16, 2026
Merged

🐛 fix(docs): resolve multiple manpage issues#3881
gaborbernat merged 2 commits intotox-dev:mainfrom
gaborbernat:3878

Conversation

@gaborbernat
Copy link
Copy Markdown
Member

Downstream packagers (Debian) reported several problems with the tox manpage introduced in #1409. The RST title block and field-list metadata created a malformed top section where SYNOPSIS and other headings were indented under an unwanted parent section. Both man_pages config and the RST source generated their own AUTHOR and COPYRIGHT sections, producing duplicates. The project variable was never set in conf.py, causing "Project name not set" to appear in the manpage header. Finally, shared-data shipped the raw .rst source file rather than a compiled troff manpage, so tox man and man tox never worked.

The RST header block is removed since man_pages already handles the title, section, and description. The AUTHOR section is kept only in the RST (with the GitHub link) while clearing the man_pages authors list to prevent duplication. The COPYRIGHT section is removed from the RST since Sphinx generates one from conf.py. Setting project = name fixes the header. A hatch build hook using docutils now compiles the manpage to troff format at wheel-build time, so pip, pipx, and uv tool install all get a working tox.1 -- and tox man can find and symlink it correctly.

Fixes #3878

@gaborbernat gaborbernat force-pushed the 3878 branch 4 times, most recently from 5d63c70 to 0fa95e7 Compare March 16, 2026 22:14
Add a hatch build hook using docutils to compile the manpage to
troff at wheel-build time so tox man and pip/pipx/uv installs get
a working tox.1 file. Remove the RST header block and field-list
(handled by man_pages config), remove the COPYRIGHT section
(generated by Sphinx from conf.py), set project in conf.py, and
clear man_pages authors list (AUTHOR kept in RST).

Fixes tox-dev#3878
@gaborbernat gaborbernat merged commit eb6ddb2 into tox-dev:main Mar 16, 2026
26 of 27 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Multiple issues with the new tox manpage

2 participants