Add indentation and new lines

[joaonc]

Seems like the spaces on each line are stripped and the only way to add a new line is by a line with just ...

It would be awesome to have escape characters that add new lines and indentation (\n and \t, for example) so that our [Documentation] tag doesn't get too big and hard to read.

Ex.:

[Documentation]  Gets n different receipt files in the receipts folder.
...
...              The files need to have the format _'receipts-XX'_ for single page receipts and _'receipt-multipage-XX'_
...              for multipage receipts and they need to be in the receipts folder.
...
...              Use the keyword ``Get Receipt Assets Path`` to get the full path to the receipt file(s).
...
...  *Arguments:*
...
...              ``NumberOfReceipts``: The number of receipt files to be returned.
...
...                  If getting one receipt, the file name is returned (no path) as string.
...
...                  If getting more than one, a list of file names is returned.
...
...              ``Pages``: Can have the following values:
...
...                     _Single_: Return only single page receipts (_'receipts-XX'_).
...
...                     _Multipage_: Return only multiple page receipts (_'receipts-multipage-XX'_).
...
...                     _Both_: Return both single and multiple page receipts.

would be more readable in the code and html with a few of the escape chars:

[Documentation]  Gets n different receipt files in the receipts folder.
...  \n          The files need to have the format _'receipts-XX'_ for single page receipts and _'receipt-multipage-XX'_
...              for multipage receipts and they need to be in the receipts folder.
...  \n          Use the keyword ``Get Receipt Assets Path`` to get the full path to the receipt file(s).
...
...  *Arguments:*\n
...              ``NumberOfReceipts``: The number of receipt files to be returned.
...  \n\t            If getting one receipt, the file name is returned (no path) as string.
...  \n\t            If getting more than one, a list of file names is returned.
...
...              ``Pages``: Can have the following values:
... \n\t                _Single_: Return only single page receipts (_'receipts-XX'_).
... \n\t                _Multipage_: Return only multiple page receipts (_'receipts-multipage-XX'_).
... \n\t                _Both_: Return both single and multiple page receipts.

[joaonc]

If you don't plan on implementing this, could you point me to the code where I can do it? tx!

[boakley]

Unfortunately, this behavior is in the robot framework itself. rfhub uses the robot tools to render the documentation. I really don't like the behavior of robot in this respect, but I thought it was important to maintain compatibility.

If you want to try to implement a different behavior, you will likely need to modify the function "doc_to_html" in rfhub/blueprints/doc/init.py

On Thu, Sep 29, 2016 at 2:16 PM, Joao Coelho notifications@github.com wrote:

If you don't plan on implementing this, could you point me to the code where I can do it? tx!

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub https://github.com/boakley/robotframework-hub/issues/72#issuecomment-250564090, or mute the thread https://github.com/notifications/unsubscribe-auth/ABEmYr6R3kRS2pJGh9CYSCEinMy2aMApks5qvA6egaJpZM4KKXpf .

[joaonc]

I'll take a look at it, but wouldn't it be a matter of string search and replace?

Ex: replace \t with 4 spaces for indentation using regex (?<!\\)(\\t). First group makes sure there's no \ escaping, second group searches for \t, so \t would be a match, \\t would not. Search for that and replace with 4 spaces, same thing with \n for new line.

Is that doable in "doc_to_html" ? (sorry, haven't looked yet).

[boakley]

It's all doable. You have to be careful though -- changes that make your documentation look good may totally break the documentation of built-in keywords. That's the problem -- it's difficult to write a converter that preserves the robot format for built-in keywords while giving better behavior for your own keywords.

Though, I suppose a simple solution might be to look for a special string in the documentation that says "use custom formatting" (eg: [Documentation] [custom-format]). The code could check for that, and if it finds it, removes it and then runs the code through your custom formatter.

On Thu, Sep 29, 2016 at 3:35 PM, Joao Coelho notifications@github.com wrote:

I'll take a look at it, but wouldn't it be a matter of string search and replace? Ex: replace \t with 4 spaces for indentation using regex (?<!)(\t). First group makes sure there's no \ escaping, second group searches for \t, so \t would be a match, \t would not. Search for that and replace with 4 spaces, same thing with \n for new line.

Is that doable in "doc_to_html" ? (sorry, haven't looked yet).

— You are receiving this because you commented. Reply to this email directly, view it on GitHub https://github.com/boakley/robotframework-hub/issues/72#issuecomment-250583408, or mute the thread https://github.com/notifications/unsubscribe-auth/ABEmYjflIQCoWsQX5985lS4RjUGNHE_Oks5qvCEGgaJpZM4KKXpf .

[joaonc]

Changed doc_to_html to this:

def doc_to_html(doc, doc_format="ROBOT"):
    """Convert documentation to HTML"""
    from robot.libdocpkg.htmlwriter import DocToHtml
    # Original code below
    # return DocToHtml(doc_format)(doc)
    # Modified code below
    import re
    html_robot = DocToHtml(doc_format)(doc)
    regex_tab = re.compile(r'(?<!\\)(\\t)')
    html_custom = regex_tab.sub('    ', html_robot)  # Convert \t to 4 spaces
    html_custom = html_custom.replace(r'\\t', r'\t')  # Convert \\t to \t
    return html_custom

Then added the \t to the comments and got the image below in the rendered html.

    ...  *Arguments:*
    ...
    ...              ``NumberOfReceipts``: The number of receipt files to be returned.
    ...
    ...                  \tIf getting one receipt, the file name is returned (no path) as string.
    ...                  \tIf getting more than one, a list of file names is returned.

We can see that \t disappears, which means it was converted to 4 spaces, but after that all multiple spaces are converted to one space (did other experiments and got the same results).

So something processes the doc after doc_to_html, even if just to replace multiple spaces to single space.

Is my assumption correct? Do you know of another place where I can further process the doc?

Thanks for your help!

[joaonc]

Ok, spent a bit more time on this. Looks like it's robot's DocToHtml that removes the \t and there's no further processing after doc_to_html.

I'll have to come up with some other syntax to add new lines, tabs and any other formatting I want..

Would be nice to have a hook in your code or in Robot's code to point to my formatter in a parameter so I don't have to change any files and be able to upgrade rfhub and robot without any other action :)

Will keep you posted. tx!