godotengine / godotengine/godot-docs

Make whitespaces visible in GDScript code samples

Open
#3,426 6 comments 0 reactions 0 assignees View on GitHub
content:website enhancement
Dominant language
reStructuredText
Stars
5.7k
Forks
3.8k
Avg merge
1d 20h
Merged PRs (30d)
25

Description

**Your Godot version:**
Any

**Issue description:**
As evident from #3423, it can be hard to understand different indent sizes in code samples. It may be only limited to the GDScript style guide, because it directly talks about various cases for the indentation, but it may make code more readable for some overall. Which is important, since GDScript is indent-sensitive language.

Unfortunately, docs don't use tabs for indents, which is a problem in itself. I think this limitation is deeply related to how Sphinx works. [Pygments can make both tabs and whitespaces visible](https://pygments.org/docs/filters/#VisibleWhitespaceFilter), if we ever solve that.

For now, we have to work with whitespaces. Ideally, to be as least obstructive as possible, we'd like to have it as an option for `::code-block` directive, but [it has no such functionality](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-code-block). So, with a little hack, that is [only going to work in Sphinx prior to version 3.x](https://www.sphinx-doc.org/en/master/extdev/appapi.html#sphinx.application.Sphinx.add_lexer), we can enforce visible whitespaces on all `gdscript` code samples.

This must be added/changed in `gdscript.py` extension:
```python
from pygments.filters import (
VisibleWhitespaceFilter,
)
...
def setup(sphinx):
l = GDScriptLexer()
l.add_filter(VisibleWhitespaceFilter(spaces=" ",wstokentype=True))
sphinx.add_lexer("gdscript", l)
```

And styles similar to this should be added in `custom.css`:
```css
.highlight .w {
position: relative;
}
.highlight .w:before {
content: "·····································";
position: absolute;
left: 0;
width: 100%;
overflow: hidden;
color: #4d566d;
user-select: none;
}
```

And this is the result:

![image](https://user-images.githubusercontent.com/11782833/79877802-5dabfc80-83f5-11ea-8b68-9ec67c0d553b.png)

Note, that these characters are ignored when a user is selecting code samples.

However, not everyone likes visible whitespace characters. Forcing it globally may be undesirable. We can try and fix this particular example instead. It would be impossible to add any character in it and not break highlighting and copying. Some may say, that in this trivial example copying is not important. Highlighter errors can also be forcefully disabled.

As a middle ground, there is an option to only make those characters visible when used in a combination with emphasized lines:

![image](https://user-images.githubusercontent.com/11782833/79878658-56d1b980-83f6-11ea-8a62-643b94976ca9.png)

To achieve this we need to make code blocks like this:
```
.. code-block::
:emphasize-lines: 2

for i in range(10):
print("hello")
```

And adjust CSS rule to be `.highlight .hll .w:before`. Highlighted lines need a small fix as well, because we do not handle them at the moment. We just need to add a proper background color for them, like `background-color: #2d3444;`.

**URL to the documentation page (if already existing):**
https://docs.godotengine.org/en/stable/getting_started/scripting/gdscript/gdscript_styleguide.html

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.