Rewrite best practices to encourage tabs

[hexylena]

While still allowing spaces, and just promoting consistency. Fixes #73

[nsoranzo]

I am heavily conflicted on this. I fully support the goal of improving accessibility, but I don't know enough about the available tools to say this is the best solution. I think we should explicitly exclude Python scripts from this recommendation, given that PEP-8, black, standard library and all major Python projects (including the Galaxy ecosystem) all use 4-space indentation. Or specify it applies only to the XML files.

[hexylena]

Yes, agreed. As written, both of these changes only affects tool XML related sections.

One is specifically in the docs/best_practices/tool_xml.rst, while the other is the last bullet of a heading Creating the Tool Wrapper (XML File)

[peterjc]

As @hexylena points out this is under an XML section, but would making the new bullet point starting "Use tabs for indentation" read "Use tabs for XML indentation" help @nsoranzo?

[nsoranzo]

Yes, agreed. As written, both of these changes only affects tool XML related sections.

One is specifically in the docs/best_practices/tool_xml.rst, while the other is the last bullet of a heading Creating the Tool Wrapper (XML File)

The Coding Style section in docs/best_practices/tool_xml.rst talks also about Python code style later on, so I think it could be confusing there.

"Tabs for XML indentation" would work for me!

[hexylena]

Fixed, per y'all's suggestion :) @nsoranzo @peterjc

[bgruening]

"Tabs for XML indentation"

This means only the XML tags inside the XML files, so not the cheetah and the rst section?

[peterjc]

Good question, can the cheetah and RST be done with either tabs or space indentation from a technical point of view?

The RST specification says at https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#whitespace that:

Spaces are recommended for indentation, but tabs may also be used.

It may be pragmatic to recommend tabs only for the XML tags, and spaces for embedded RST?

[hexylena]

I'd like to see it recommended for the cheetah sections as well (that's always worked fine) and since by their documentation it works fine for rST, I'd argue we should provide a more consistent guidance, namely:

• tabs are suggested for all parts, the XML, the cheetah (works), and the rST (supported!)
• and if you are consistent, you are permitted to use spaces for all three
• we do not recommend mixing tabs and spaces in the file, consistency is encouraged

[bgruening]

I think we are pretty much a Python community (cheetah, rst ...) and they recommend spaces instead of tabs. I don't see why we should recommend tabs here.

Maybe we can remove the current recommendation and just not recommend anything, just staying stay consistent. Overall the important part is that people can use what they can deal with best.

[hexylena]

I don't see why we should recommend tabs here.

This discussion in a large part was started by wanting to make things more accessible to everyone, and more welcoming for those users, hence making that the recommendation, but allowing it open to personal choice.

and just not recommend anything, just staying stay consistent

As it stands, with the text as it is now, any contributor would be free to stick with spaces. But by having the recommendation we can at least push for some small tiny amount of slow change in a positive direction.

The only time having this "recommendation" would be bad, is if a reviewer decided to ignore that it is a "recommendation" and make it mandatory for a contributor.