Sphinx for reStructuredText (reST): Parser falling short

[vanledem]

Hello,

I have been using your tool for a few months and it is great for making small docstrings in ReST where the amount of information stays significantly low (typically 10 lines with the arguments and the return). However once I use all the functionalities that are available in ReST which allow for a much more complex output in Sphinx, I'm unable to obtain the equivalent result.

Would It be possible to manage those Sphinx-ReST functionalities into the tool (I will update when I'm home with an example)?

Currently, I'm using directly Sphinx to produce the documentation of each project separately and then I'm using pydoc-markdown to integrate with CI/CD the documentation of the differents projects to put it into a single gitlab pages.

Thanks you for your time, I'm happy to help you to investigate and implement a better system on that specific subject but I fear it is above my pay-grade for now.

Docstring raw

    """A short description of the script
    A more verbose description of the script.
    In this verbose description, a new line need to be explicit, I can either set a blank line or setup a line block

    | This will be a line block, each line is configured to be aligned on the left side
      without creating a new paragraph, usefull therefore in setting a specific kind of layout.
    | This is another aligned line which is supposed to be in the same paragraph.

    This is a new paragraph, as you can see, the lines are not alined, nor there is a
    way get back to a new line that is working both for sphinx and for pydoc-markdown.

    :Additional field: This is an additional field that details either specific information about the function,
        such as a the creator, the version, if it is depreciated (I mean see the ReST documentation about it).
        But I can add my own fields and they should be shown in the docstring

    :param node: Here is a definition of param1
    :type node: Type of the param1
    :param filepath: | Here is a first part of the description of the param
        | This is a second part of the description of the param
          with a second line which will be continuing
    ..
     :Hello World: This is supposed to be commented, it is mainly so that documentation can be see internally but
        not exported
     :This is a second field: | We can comment stuff by putting two points, adding one or several spaces for alignement
        | We wanted it to be on two aligned lines

    :return: | This is the explaination of the return statement, as it is quite long, I will align it aswell.
        | This is the second line (aligned with the first one), as it is very long and I want to see all the line,
          I will have to get back to the line but it is still continuing it.
        | Hope this will explain more the issues that I face
    """

Sphinx output:

Pydoc-Markdown output:

PS: Update with Example

[NiklasRosenstein]

Hi @vanledem,

This is a limitation by how much of the ReST syntax we support and convert into corresponding Markdown format. There's also the issue that ReST syntax elements don't have a counterpart in Markdown. If you have any suggestions on how to convert a particular ReST syntax to Markdown, feel free to include those here. Then we'd still need someone willing to work on the code to convert the syntax. :)

I suppose we could also consider looking into pandoc for ReST -> Markdown conversion

[vanledem]

Hello @NiklasRosenstein,

As I mentionned previously, I'm far from being an expect here. The issue I think we need to address for the specific field '|' which is indicating that within a code block we have mutliples lines, each ones starting with the '|'. I have additional issues with custom fields such out of the classical fields that are already implemented into the code (param, return) here illustrated with the :additional field: part. I have no clue how I should eventually implement it on your project but I would be happy to provide you additional examples.

Best regards