tk0miya
commented
4 years ago (1) "Sphinx focuses on documentation, in particular handwritten documentation": I suspect that what's meant here is "human-generated documentation" rather than "handwritten documentation". Sphinx doesn't do optical character recognition on handwriting.
+0; I agree the wording is not good. I thought they do not have a special meaning. So I feel it's also good to remove them.
(2) "The toctree directive initially is empty, and looks like so:": This comment is followed by a bunch of not terribly illuminating blank space.
+1: It is better not to use "sidebar" directive here.
(3) What do the two dots in front of the toctree signify? Is any directive supposed to be preceded by two dots? (4) It is good to know that directives are versatlile, but what is the general purpose of directives? This is never explained.
I can't answer it well. Please read the document of reST: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#directives
(5) Is a toctree directive the only way to get an entry added to the table of contents?
Basically yes. But it's not prohibited. So 3rd party extension can do it.
(6) "A common gotcha with directives is that the first line of the content must be indented to the same level as the options are." What about subsequent lines?
They are also indented if they are part of the contents of the directive.
(7) Do directives have scope, or is that concept inapplicable?
Surely, some directives have their scope. But some don't have. Please read the document of each directive.
Phillip-M-Feldman
This page is unclear on a number of items; the following is a partial list:
(1) "Sphinx focuses on documentation, in particular handwritten documentation": I suspect that what's meant here is "human-generated documentation" rather than "handwritten documentation". Sphinx doesn't do optical character recognition on handwriting.
(2) "The toctree directive initially is empty, and looks like so:": This comment is followed by a bunch of not terribly illuminating blank space.
(3) What do the two dots in front of the toctree signify? Is any directive supposed to be preceded by two dots?
(4) It is good to know that directives are versatlile, but what is the general purpose of directives? This is never explained.
(5) Is a toctree directive the only way to get an entry added to the table of contents?
(6) "A common gotcha with directives is that the first line of the content must be indented to the same level as the options are." What about subsequent lines?
(7) Do directives have scope, or is that concept inapplicable?