Inconsistent styles in keyword documentation

[pekkaklarck]

Keyword docs mainly use Robot Frameworks own documentation format but there are several places where reStructuredText is used instead. This is far from optimal because now the docs aren't valid in either of these formats.

Libdoc supports both Robot's own format and reST so either of them can be used. The former is simpler and more commonly used with Robot libraries, but the latter allows generating docs also using standard Python documentation tools. Any comments which should be used? Personally I don't have a strong opinion either way.

If Robot's format is used, it would be a good idea to change formatting of arguments to use double backticks instead of single backticks. The latter is generally used by Libdoc for internal linking, and using it for other formatting can create accidental links. The former style is new in RF 2.8.6 and thus creates a dependency for RF version to be used go generate docs.

Regardless the chosen format, it would be good to review docs in general and see is there outdated information. At least a link to User Guide still points to Google Code.

[zephraph]

To be honest I haven't looked into either format. I've basically been copying the precedent.

With that being said, I'm all for moving more towards Robot's format. I plan on tackling some documentation related stuff for the next release so I'll just add this to the list.

[pekkaklarck]

reST can definitely be a good choice too, but mixing reST and Robot formats is bad. These formats ought to be pretty much equivalent in this particular usage. Only limitation that I'm aware is that reST format doesn't support creating and linking to custom section titles, but I could take a look could that support be added in RF 2.9a2 if needed. I doubt reST format has been used with such a big library as Se2Lib, so there may be also other issues.

[pekkaklarck]

reST usages I've noticed in general library docs:

• Line 41 tries to use literal blocks with :: at the end. Could use Robot's preformatted text instead.
• Line 72 seems to have same issue as above but only has : at the end.
• Line 108 contains anonymous link. Could use Robot's link syntax instead.

Other possible changes:

• When referring to arguments, use double backticks "code style" instead of single backticks that can create internal links.
• Consider using double backticks to format also examples. Currently some examples are quoted (e.g. '=') and others formatted as italics (e.g. _page?a_).
• Change plain URLs to links when it makes sense. For example, URL on line 93 could be changed to a link (and the actual URL updated).
• Use table headers like = Header = instead of bold like * Header *.

Many of the above suggestions are pretty minor but may be worth doing if docs are reviewed in general. I'm also willing to help with these changes if needed.

[zephraph]

I went ahead and removed the generated doc from master. The actual docs are stored in the gh-pages branch.

I'll create an update-documentation branch and we can start chipping away at it on there.

[zephraph]

@pekkaklarck, feel free to make any changes against that branch. Let's focus on moving everything to robot's style too.

[pekkaklarck]

@zephraph great! I'm burning midnight oil here and trying to get some emails answered but could have time for that tomorrow or during weekend.

[pekkaklarck]

One theme of v2.0 is going to be cleaning up the project. Fixing documentation styles definitely fits into that theme well. Should also look at all other issues related to documentation. Most of them seem to be related to improving docs of individual keywords.

[aaltat]

I agree that we should use constant style with keyword documentation. And have documentation available which style to use when users send pull request. I don't feel strongly which style we should use and it's seems that no one else doesn't feel strongly about the style.

Coder me feels that rst would be better, because it's more powerful. The tester me feels that it might too complicated for testers to make. The coder me is slightly winning, but should we go to same direction which is used with Robot Framework libraries (no idea what that actually is)?

[emanlove]

If the Robot Framework tools only work or work better with the robot format then we should use robot format. Although rst is the standard for python since we have no outside documentation (like thorough Read The Docs for example) nor any Seleniun2Library specific documentation tools then I see no reason at this time to go with rst.

I guess the one exception to this would be the documentation on PyPI which for simplicity and maintainability sake I would say provide the bear minimum there and point everyone somewhere "here" or "on our side". This way we only have to maintain one set of documents.

[aaltat]

I did read Robot user guide and it says rst is supported starting from 2.7.5 (with libdoc). I also like the idea of one set of documentation, which rst provides.

If none has a good reason to argue to other way, let's go with rst.

[pekkaklarck]

I'm starting to like the idea to use reST as well. One problem with it is that currently Libdoc doesn't support syntax highlighting code blocks. That's a big miss because code blocks could be used to show Robot examples as well as Python code. Good news is that adding highlighting support for Libdoc isn't too complicated. See robotframework/robotframework#2448 for details.

[pekkaklarck]

If we go with reST, we need to decide how to document arguments. Unfortunately there is no single official standard for that, but at least Google style, NumPy style and Sphinx default style are commonly used. For a somewhat biased comparison between these formats see https://sphinxcontrib-napoleon.readthedocs.io/en/latest/.

Sphinx style is used in Robot's code when documenting public APIs and it has been OK. It's a bit verbose and ugly, but a big benefit is that at least PyCharm recognized the syntax and can do code inspection based on the information. Google style looks a lot better, but we should test do IDEs support it the same way as Sphinx style.

We should also test how different argument specification styles work with Libdoc. It's possible that further Libdoc enhancements are needed.

[pekkaklarck]

General library docs have been enhanced as part of #924 and we have #925 about going through docs of each keyword too. This issue can be closed in favor of them.