search

click-contrib / sphinx-click

A Sphinx plugin to automatically document click-based applications
MIT License
212 stars 57 forks source link

Misaligned prog name #61

Closed WhyNotHugo closed 4 years ago

WhyNotHugo commented 4 years ago

The name of my program is misaligned by being further indented than it should be. E.g.:

TODOMAN(1)                Todoman               TODOMAN(1)

NAME
       todoman - a simple, standards-based, cli todo

TODO
          todo [OPTIONS] COMMAND [ARGS]...

       Options

Note than todo [OPTIONS is further right than it should be. For comparison, man(1):

MAN(1)                    Manual pager utils                    MAN(1)

NAME
       man - an interface to the system reference manuals

SYNOPSIS
       man [man options] [[section] page ...] ...
       man -k [apropos options] regexp ...
       man -K [man options] [section] term ...

Also, rather than TODO, this should say SYNOPSIS.

stephenfin commented 4 years ago

I think you have the wrong project. sphinx-click doesn't do anything special for man pages. You're looking for either click-man or Sphinx itself.

WhyNotHugo commented 4 years ago

Sphinx itself generates man pages based on rst, and I'm using the directive in sphinx-click:

.. click:: todoman.cli:cli
   :prog: todo
   :show-nested:
stephenfin commented 4 years ago

Gotcha. What I'm saying is that sphinx-click doesn't do anything special for that builder. It generates the same rST output regardless of builder and Sphinx converts this to the required output format. We could special case the man builder to generate a different heading, but we don't do this currently and, given click-man exists, I don't think we need to.

WhyNotHugo commented 4 years ago

click-man is a no-go for me since our docs are already written in sphinx, an I want to re-use between the html and man versions as much as possible.

I'll try and figure out how to work around using sphinx-click :)

stephenfin commented 4 years ago

Okay. The best option I can think of aside from checking the builder configured at runtime is to allow the output to be templated, ideally using jinja2. Currently that's all generated by hand, so the conversion should be possible, albeit potentially laborious. I'd be happy to accept either approach given sufficient tests, but it's not high enough priority to work on myself, unfortunately.