sphinx
sphinx copied to clipboard
sphinx-doc
Conflicting docs regarding code-block spaces
Describe the bug
- This sphinx-doc shows code block content with 3 spaces
- This other sphinx-doc shows an example with 7 spaces (scroll down to
.. code-block::) - Anaconda's rst cheatsheet (not official, but "big name official cheatsheet") examples 4 spaces
I then receive warnings "expecting max 1 arg" when I use 3 spaces with :linenos: that goes away when I give it 4 spaces (misaligned!).
Overall, it's wildly confusing:
- Can anyone clarify the official way to do this, with and without
:linenos:(if it makes a difference -- I don't know why it would change the alignment)? - Is it possible to update these docs to both use the same spacing examples, and perhaps have an example using
:linenos:as well?
This code-block is very mysterious.
How to Reproduce
Compare my links above
Environment Information
Platform: win32; (Windows-10-10.0.22631-SP0)
Python version: 3.10.11 (tags/v3.10.11:7d4cc5a, Apr 5 2023, 00:38:17) [MSC v.1929 64 bit (AMD64)])
Python implementation: CPython
Sphinx version: 7.4.7
Docutils version: 0.20.1
Jinja2 version: 3.1.4
Pygments version: 2.18.0
Sphinx extensions
n/a
Additional context
No response
Heya, In the one of the links you provide, it gives the answer 😅 https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#directives
Be careful as the indent is not a fixed number of whitespace, e.g. three, but any number whitespace. This can be surprising when a fixed indent is used throughout the document and can make a difference for directives which are sensitive to whitespace. Compare: ...
I don't know if my coffee isn't kicking in or what, but can you provide an alternate example? In the explanation in the doc, it gives 2 identical code block spaces. I thought the 2nd code block would have been aligned to the directive with -4 spaces, but it's the same, so why does it have no spaces at the beginning?
its determined by the indent of the "first non-blank line"
.. directive::
non-blank
.. directive::
non-blank
the first non-blank line of the first one is :caption:
Thank you - Ahh gotcha I think that's what threw me off: I would never have expected an arg like :caption: be the "starting" non blank line; I very much assumed the code content after hard-coding into my head to always align with the directive / 3 spaces.
I'd propose to change this sphinx-doc to have the code example be more educational rather than "this is a ruby code block". Something in regards to line spacing, and how the args, too, must align with the spacing (rather than the directive - which is what we're previously trained to do instinctively).
so why does it have no spaces at the beginning?
The general rules of indentation always hold; that's to say the parser will count the number of spaces (indentation level) of the first non-blank line and expect any subsequent lines within a given block to be consistent relative to that level.
so why does it have no spaces at the beginning?
Because the parser strips indentation when processing a directive.
The 7 spaces are an outlier and should be fixed.
We should aim at consistent spacing. It's similar to Python: While you can use any indentation as long as you obey the indentation rules, it good to have a consistent best practice.
Docutils as the original source mostly uses 3 spaces, but they are not consistent themselves and also have cases of 4 spaces and on some occasions 2 spaces.
The Sphinx docs mostly uses 3 spaces. I assume this comes from docutils.
I can see an argument for 4 spaces (and partly use this in my projects). In particular in docstrings it is hard to have the docstring indented by multiples of 4 and then add multiples of 3 rst indenting on top. But changing all the indentation in the Sphinx docs is a discussion of its own.
Docutils as the original source mostly uses 3 spaces (...) 4 spaces (...) 2 spaces.
I think the main concern is that it's potentially confusing to beginners.
The Sphinx docs mostly uses 3 spaces. I assume this comes from docutils.
Afaict the original Sphinx discussions boards that might contain the rational for using 3 space indentation are gone since the project migrated to GitHub. The original rational for docutil's using 3 space indentation was likely in some Python sig-group discussion board that's most likely also been deleted. (It might be a good time to ask in case some future archeologist wonders about the 3 space indentation.)
In particular in docstrings it is hard to have the docstring indented by multiples of 4 and then add multiples of 3 rst indenting on top.
My solution is hitting the Tab regardless as I've never found a reason to use 3 space besides following the documentation examples.
The original rational for docutil's using 3 space indentation was likely in some Python sig-group discussion board that's most likely also been deleted.
The full archives of DOC-Sig going back to 1998(?) still exist.
If I had to guess at the reason for three space indentation, it is simply that explicit markup in reST uses \.\. +\w\s*::, and hence the minimum amount of leading indentation is three (.. ). I doubt it was an intentional choice, more one that led on from how directives are specified. Note eg lists have a variable indentation, so this is not consistent.
A
Reading this discussion I discovered a mis-behavior of the "electric-mode" of Emacs in a buffer triggering the ReST major mode. After having typed:
.. note::
hello
.. note::
:name: test
tabbing brought me here
The TAB key wll align with "test". Thus output will have extra spaces, as per the current discussion. And I tested with rst2html which produces:
Maybe my Emacs ReST mode support is outdated. Hmm it seems to come with the binary build of Emacs I installed on MacOS via homebrew, I am still using Emacs 28.1. The source at my computer says
;; The latest release of this file lies in the docutils source code repository:
;; http://docutils.svn.sourceforge.net/svnroot/docutils/trunk/docutils/tools/editors/emacs/rst.el
but I can't find any version string in it apart from
;; Copyright (C) 2003-2022 Free Software Foundation, Inc.
Perhaps I will open a ticket at Docutils home regarding their Emacs rst.el. But first I need to check with their latest version...
Docutils doesn't maintain rst.el any more, it moved to emacs itself. https://github.com/emacs-mirror/emacs/blob/master/lisp/textmodes/rst.el is the latest I believe.
A
Thanks @AA-Turner I was 2 seconds away from posting my already written ticket at the Docutils site...
EDIT: I tested with latest version loaded, same behavior. I opened a ticket at Emacs with a nice spelling mistake in the title and the mail address I take some much pain to obfuscate on GitHub...
Docutils really is that library
That is true. OTOH it feels like their dev workflows are still from 2003 as well - sourceforge does not have a reasonable developer experience. This makes contributing hard (I've been through this) and thus they don't get much support from new contributors.
If I had to guess at the reason for three space indentation, it is simply that explicit markup in reST uses
\.\. +\w\s*::, and hence the minimum amount of leading indentation is three (..).
Actually, the minimal indentation is ONE. Example:
.. topic:: topic title
Topic text.
*
bullet list
.. code:: python
:name: world
print("hello world")
This may help when browsing rST sources on a smartphone :)
This other sphinx-doc clarifies "the official way to do this, with and without :linenos:" in detail.
It may be amended with another indentation peculiarity: without option block, the least indented line of the content block determines what is stripped:
.. code-block::
The output of this line starts with four spaces.
The output of this line has no spaces at the beginning.
This line is not part of the code block.
@timhoffm
The 7 spaces are an outlier and should be fixed.
The 7 spaces are an essential part of the example detailling the behaviour. The text before and after it explains this clearly.