CODEWITHSUNDEEP
python-sphinxrestructuredtext
Ashwin
Ashwin

Reputation: 93

Remove blank line generated due to comments in restructured text

I am writing documentation in RST and generating HTML using Sphinx.

I want to comment out some text but the HTML is inserting a blank line.

* Line1
.. * Line2
* Line3
* Line4

The HTML prints a blank line between Line1 and Line3. How do I remove this blank line?

Upvotes: 2

Views: 543

Answers (2)

leogama
leogama

Reputation: 1059

@user4184837's answer helped me to figure out a nice hack to comment out, for example, parameter descriptions in a function without breaking the output layout.

Below is an example this method that abuses the :meta: fields of reST field lists.

Original documentation version.

.. py:function:: func(arg1, arg2, opt1=True, opt2=False)

    func description.

    :param arg1: first argument description
    :param arg2: second argument description
    :param opt1: an optional parameter
    :param opt2: another optional parameter
    :returns: the result

Same documentation with parameter opt2 removed and its description commented out, and a replace directive inserted between the param fields.

.. py:function:: func(arg1, arg2, opt1=True)

    func description.

    :param arg1: first |desc|
    :param arg2: second |desc|
    :meta:
        .. |desc| replace:: argument description
    :param opt1: an optional parameter
    :meta param opt2: another optional parameter
    :returns: the result

This can also be achieved using Google-style documentation with the Sphinx extension napoleon, but the :meta: fields must be moved to after the Args/Parameters block. Even though, using these still preserves the spacing between the blocks (e.g. between Args and Returns).

def func(arg1, arg2, opt1=True):
    """
    func description.

    Args:
        arg1: first |desc|
        arg2: second |desc|
        opt1: an optional parameter
    :meta _ opt2: another optional parameter
    :meta:
        .. |desc| replace:: argument description

    Returns:
        The result.
    """

Upvotes: 0

user4184837
user4184837

Reputation:

Your reST is faulty as it is missing blank lines. Besides, you should indent the comment to avoid ending the list and then start a new one.

* Line1

  .. * Line2

* Line3
* Line4

Upvotes: 4

Related Questions