documentation pandoc restructuredtext manpage groff

Missing ".TH" section when converting .rst file to groff format in pandoc (reStructuredText, manpage)

What should I put in a source reStructuredText file to populate the "Title Heading" (.TH) line in the destination file when using pandoc to convert it to groff-format?

I have a python project whose documentation is built with sphinx. As such, most of the project's documentation is already written in reStructured Text (.rst files). I need to write a manpage, so I'd like to write it in reST format.

Unfortunately, when I use pandoc to convert the source .rst file to man (groff-format), the file doesn't render properly with man since it's missing the Title Heading.

For example, consider the following source file source.rst

==========
my-program
==========

----------------------
my-program description
----------------------

:manual section: 1
:manual group: John Doe

Synopsis
========

**my-program**

Description
===========

**my-program** is magical. It does what you need!

I use pandoc to convert it to groff format as follows:

user@disp117:~$ pandoc source.rst -t man > my-program.1
user@disp117:~$ 

user@disp117:~$ cat my-program.1 
.SH my-program
.SS my-program description
.TP
manual section
1
.TP
manual group
John Doe
.SS Synopsis
.PP
\f[B]my-program\f[R]
.SS Description
.PP
\f[B]my-program\f[R] is magical.
It does what you need!
user@disp117:~$

Now, if I try to render that groff file, then it doesn't format properly.

user@disp117:~$ groffer --text my-program.1 
manual  section  1 manual group John Doe my‐program my‐program is
magical.  It does what you need!
...

However, if I manually add the a .TH line to the file, then it works as expected.

user@disp117:~$ echo -e ".TH my_program(1)\n$(cat my-program.1)" > my-program.1
user@disp117:~$ 

user@disp117:~$ groffer --text my-program.1 
my_program(1)()                                                my_program(1)()



my-program
   my-program description
       manual section
              1

       manual group
              John Doe

   Synopsis
       
       [B]my-program
                    [R]

   Description
       
       [B]my-program
                    [R] is magical.  It does what you need!



                                                               my_program(1)()
user@disp117:~$

What do I need to add to source.rst such that pandoc will produce a file in groff-format that includes the .TH line?

Solution

Pandoc generates "snippets" by default; those snippets are intended to be integrated into a complete document. Make pandoc generate a complete document with

   pandoc --standalone ...

   pandoc -s ...