Repository: sphinx-doc/sphinx

Issue:
code-block captions are not displayed correctly in man pages
### Problem
code-block captions are not displayed correctly in man pages

#### Procedure to reproduce the problem
Run the following:
```
mkdir /tmp/code-block-test
cd /tmp/code-block-test
yes "n" | sphinx-quickstart --dot _ --project code-block-test --author "Example" -v 0 --release 0 --language en --suffix .rst --master index --makefile --batchfile docs
echo '
Below is an example of a codeblock with a caption.

.. code-block:: bash
   :caption: This is a caption

   echo 1234
' >> docs/index.rst
make -C docs man
```

#### Error logs / results
The rendered man page contains:
```
       Below is an example of a codeblock with a caption. This is a caption.INDENT 0.0

          echo 1234
```

#### Expected results
".INDENT 0.0" should not appear in the man page.

I would expect the rendered version of the man page to look more like:

```
       Below is an example of a codeblock with a caption.

       This is a caption

          echo 1234
```

(This would be consistent with the behavior of `html` and `latexpdf`.)

### Reproducible project / your project
See above.

### Environment info
- OS: Ubuntu 16.04 LTS
- Python version: Python 2.7.12
- Sphinx version: Sphinx v1.5.6

Discussion:
codecov[bot]: # [Codecov](https://codecov.io/gh/sphinx-doc/sphinx/pull/6159?src=pr&el=h1) Report
> :exclamation: No coverage uploaded for pull request base (`1.8@f57041a`). [Click here to learn what that means](https://docs.codecov.io/docs/error-reference#section-missing-base-commit).
> The diff coverage is `100%`.

[![Impacted file tree graph](https://codecov.io/gh/sphinx-doc/sphinx/pull/6159/graphs/tree.svg?width=650&token=VFlFSELbkw&height=150&src=pr)](https://codecov.io/gh/sphinx-doc/sphinx/pull/6159?src=pr&el=tree)

```diff
@@          Coverage Diff           @@
##             1.8    #6159   +/-   ##
======================================
  Coverage       ?   82.16%           
======================================
  Files          ?      308           
  Lines          ?    39979           
  Branches       ?     6068           
======================================
  Hits           ?    32847           
  Misses         ?     5693           
  Partials       ?     1439
```


| [Impacted Files](https://codecov.io/gh/sphinx-doc/sphinx/pull/6159?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [tests/test\_build\_manpage.py](https://codecov.io/gh/sphinx-doc/sphinx/pull/6159/diff?src=pr&el=tree#diff-dGVzdHMvdGVzdF9idWlsZF9tYW5wYWdlLnB5) | `100% <100%> (ø)` | |
| [sphinx/writers/manpage.py](https://codecov.io/gh/sphinx-doc/sphinx/pull/6159/diff?src=pr&el=tree#diff-c3BoaW54L3dyaXRlcnMvbWFucGFnZS5weQ==) | `91.22% <100%> (ø)` | |

------

[Continue to review full report at Codecov](https://codecov.io/gh/sphinx-doc/sphinx/pull/6159?src=pr&el=continue).
> **Legend** - [Click here to learn more](https://docs.codecov.io/docs/codecov-delta)
> `Δ = absolute <relative> (impact)`, `ø = not affected`, `? = missing data`
> Powered by [Codecov](https://codecov.io/gh/sphinx-doc/sphinx/pull/6159?src=pr&el=footer). Last update [f57041a...6fa92ff](https://codecov.io/gh/sphinx-doc/sphinx/pull/6159?src=pr&el=lastupdated). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments).


Patch:
diff --git a/CHANGES b/CHANGES
index 0b2c97c7b..f4bddaf25 100644
--- a/CHANGES
+++ b/CHANGES
@@ -30,6 +30,7 @@ Bugs fixed
 * #6136: ``:name:`` option for ``math`` directive causes a crash
 * #6139: intersphinx: ValueError on failure reporting
 * #6135: changes: Fix UnboundLocalError when any module found
+* #3859: manpage: code-block captions are not displayed correctly
 
 Testing
 --------
diff --git a/sphinx/writers/manpage.py b/sphinx/writers/manpage.py
index 9ce9f7293..20b1d07e1 100644
--- a/sphinx/writers/manpage.py
+++ b/sphinx/writers/manpage.py
@@ -462,6 +462,21 @@ def depart_manpage(self, node):
         # type: (nodes.Node) -> None
         return self.depart_strong(node)
 
+    # overwritten: handle section titles better than in 0.6 release
+    def visit_caption(self, node):
+        # type: (nodes.Element) -> None
+        if isinstance(node.parent, nodes.container) and node.parent.get('literal_block'):
+            self.body.append('.sp\n')
+        else:
+            BaseTranslator.visit_caption(self, node)
+
+    def depart_caption(self, node):
+        # type: (nodes.Element) -> None
+        if isinstance(node.parent, nodes.container) and node.parent.get('literal_block'):
+            self.body.append('\n')
+        else:
+            BaseTranslator.depart_caption(self, node)
+
     # overwritten: handle section titles better than in 0.6 release
     def visit_title(self, node):
         # type: (nodes.Node) -> None


Test patch:
diff --git a/tests/test_build_manpage.py b/tests/test_build_manpage.py
index 0a22d3ab6..6596e83b6 100644
--- a/tests/test_build_manpage.py
+++ b/tests/test_build_manpage.py
@@ -25,3 +25,24 @@ def test_all(app, status, warning):
     # term of definition list including nodes.strong
     assert '\n.B term1\n' in content
     assert '\nterm2 (\\fBstronged partially\\fP)\n' in content
+
+
+@pytest.mark.sphinx('man', testroot='directive-code')
+def test_captioned_code_block(app, status, warning):
+    app.builder.build_all()
+    content = (app.outdir / 'python.1').text()
+
+    assert ('.sp\n'
+            'caption \\fItest\\fP rb\n'
+            '.INDENT 0.0\n'
+            '.INDENT 3.5\n'
+            '.sp\n'
+            '.nf\n'
+            '.ft C\n'
+            'def ruby?\n'
+            '    false\n'
+            'end\n'
+            '.ft P\n'
+            '.fi\n'
+            '.UNINDENT\n'
+            '.UNINDENT\n' in content)