Sphinx gotchas - Revision history

StefanoZacchiroli: /* Code cross-references */ document explicit anchors

2018-01-22T15:28:30Z

Code cross-references: document explicit anchors

← Older revision		Revision as of 15:28, 22 January 2018
Line 118:		Line 118:
	<pre>		<pre>
	see the :func:`do_something` function and the :mod:`swh.useless` module for more information		see the :func:`do_something` function and the :mod:`swh.useless` module for more information
			</pre>

			<u>Good:</u>
			<pre>
			you can avoid a long, fully-qualified anchor setting an :func:`explicit label <swh.long.namespace.function>` for a link
	</pre>		</pre>

StefanoZacchiroli: /* Code cross-references */

2017-09-07T14:11:16Z

Code cross-references

← Older revision		Revision as of 14:11, 7 September 2017
Line 120:		Line 120:
	</pre>		</pre>

	Note that you can (and should) omit the `:py:` prefix, as Python is the default domain.		See also: the [http://www.sphinx-doc.org/en/stable/domains.html#cross-referencing-python-objects list of Python roles] that you can use to cross-reference Python objects. Note that you can (and should) omit the <code>:py:</code> prefix, as Python is the default domain.

			Note also that when building Sphinx documentation for individual Software Heritage modules in isolation, cross-references to other modules will ''not'' be resolvable. But they will be resolvable when building the unified documentation from <code>swh-docs</code>.

	== Napoleon ==		== Napoleon ==

StefanoZacchiroli: /* Sphinx */ add gotcha: code cross-references

2017-09-07T14:07:34Z

Sphinx: add gotcha: code cross-references

@@ Line 105: / Line 105: @@
 additional \**kwargs are copied in the returned dictionary
 </pre>
 == Napoleon ==

StefanoZacchiroli: /* Sphinx */ add gotcha: asterisk escape

2017-09-07T14:03:26Z

Sphinx: add gotcha: asterisk escape

@@ Line 90: / Line 90: @@
 <pre>
 you have to instantiate the method ``def foo(bar): pass`` in order to use this abstract class
 </pre>

StefanoZacchiroli: /* Napoleon */ add gotcha: Raises section

2017-09-07T14:00:13Z

Napoleon: add gotcha: Raises section

@@ Line 154: / Line 154: @@
 <pre>
 Returns: this is not good either, you need to start a paragraph
 </pre>

StefanoZacchiroli: /* Napoleon */

2017-09-07T13:58:06Z

Napoleon

← Older revision		Revision as of 13:58, 7 September 2017
Line 103:		Line 103:
	Continuation lines should be indented.		Continuation lines should be indented.

	Bad:		<u>Bad:</u>
	<pre>		<pre>
	Args:		Args:
Line 111:		Line 111:
	</pre>		</pre>

	Good:		<u>Good:</u>
	<pre>		<pre>
	Args:		Args:
Line 124:		Line 124:
	In Returns section you need to use ":" carefully as, if present, it will be interpreted as a separator between return type and description. Also, the description of return value should not start on the same line of "Returns:", but on the subsequent one, indented.		In Returns section you need to use ":" carefully as, if present, it will be interpreted as a separator between return type and description. Also, the description of return value should not start on the same line of "Returns:", but on the subsequent one, indented.

	Bad:		<u>Bad:</u>
	<pre>		<pre>
	Returns:		Returns:
Line 133:		Line 133:
	<pre>		<pre>

	Good:		<u>Good:</u>
	<pre>		<pre>
	Returns:		Returns:
Line 142:		Line 142:
	</pre>		</pre>

	Good:		<u>Good:</u>
	<pre>		<pre>
	Returns:		Returns:
Line 151:		Line 151:
	</pre>		</pre>

	Bad:		<u>Bad:</u>
	<pre>		<pre>
	Returns: this is not good either, you need to start a paragraph		Returns: this is not good either, you need to start a paragraph

StefanoZacchiroli: /* Sphinx */

2017-09-07T13:57:28Z

Sphinx

← Older revision		Revision as of 13:57, 7 September 2017
Line 7:		Line 7:
	All sorts of [http://www.sphinx-doc.org/en/stable/rest.html#lists-and-quote-like-blocks '''lists'''] require an empty line before the first bullet and after the last one, to be properly interpreted as list. No indentation is required for list elements w.r.t. surrounding text, and line continuations should be indented like the first character after the bullet		All sorts of [http://www.sphinx-doc.org/en/stable/rest.html#lists-and-quote-like-blocks '''lists'''] require an empty line before the first bullet and after the last one, to be properly interpreted as list. No indentation is required for list elements w.r.t. surrounding text, and line continuations should be indented like the first character after the bullet

	Bad:		<u>Bad:</u>
	<pre>		<pre>
	this is a bad example that will not be interpreted as a list		this is a bad example that will not be interpreted as a list
Line 17:		Line 17:
	</pre>		</pre>

	Good:		<u>Good:</u>
	<pre>		<pre>
	this is some text preceding the list		this is some text preceding the list
Line 31:		Line 31:
	</pre>		</pre>

	Bad:		<u>Bad:</u>
	<pre>		<pre>
	- foo		- foo
Line 40:		Line 40:
	</pre>		</pre>

	Good:		<u>Good:</u>
	<pre>		<pre>
	surrounding text		surrounding text
Line 59:		Line 59:
	Verbatim [http://www.sphinx-doc.org/en/stable/rest.html#source-code '''code blocks'''], e.g., for code examples, requires double colon at the end of a line, then an empty line, and then the code block itself, indented:		Verbatim [http://www.sphinx-doc.org/en/stable/rest.html#source-code '''code blocks'''], e.g., for code examples, requires double colon at the end of a line, then an empty line, and then the code block itself, indented:

	Bad:		<u>Bad:</u>
	<pre>		<pre>
	This does not work as there is a single column and no empty line before code:		This does not work as there is a single column and no empty line before code:
Line 68:		Line 68:
	</pre>		</pre>

	Good:		<u>Good:</u>
	<pre>		<pre>
	a nice example of python code follows::		a nice example of python code follows::
Line 82:		Line 82:
	'''Inline code samples''' use double backquotes, and not single ones.		'''Inline code samples''' use double backquotes, and not single ones.

	Bad:		<u>Bad:</u>
	<pre>		<pre>
	you have to instantiate the method `def foo(bar): pass` in order to use this abstract class		you have to instantiate the method `def foo(bar): pass` in order to use this abstract class
	</pre>		</pre>

	Good:		<u>Good:</u>
	<pre>		<pre>
	you have to instantiate the method ``def foo(bar): pass`` in order to use this abstract class		you have to instantiate the method ``def foo(bar): pass`` in order to use this abstract class

StefanoZacchiroli: reorder good/bad sections

2017-09-07T13:55:06Z

reorder good/bad sections

← Older revision		Revision as of 13:55, 7 September 2017
Line 6:		Line 6:

	All sorts of [http://www.sphinx-doc.org/en/stable/rest.html#lists-and-quote-like-blocks '''lists'''] require an empty line before the first bullet and after the last one, to be properly interpreted as list. No indentation is required for list elements w.r.t. surrounding text, and line continuations should be indented like the first character after the bullet		All sorts of [http://www.sphinx-doc.org/en/stable/rest.html#lists-and-quote-like-blocks '''lists'''] require an empty line before the first bullet and after the last one, to be properly interpreted as list. No indentation is required for list elements w.r.t. surrounding text, and line continuations should be indented like the first character after the bullet

			Bad:
			<pre>
			this is a bad example that will not be interpreted as a list
			preceding text
			- foo
			- bar
			- baz
			following text
			</pre>

	Good:		Good:
Line 23:		Line 33:
	Bad:		Bad:
	<pre>		<pre>
	~~this is a bad example that will not be interpreted as a list~~
	~~preceding text~~
	- foo		- foo
	- ~~bar~~		- nested lists also requires empty lines, but they are missing here
	- ~~baz~~		- inner list 1
	~~following text~~		- inner list 2
			- outer list continues here
	</pre>		</pre>

Line 45:		Line 54:
	surrounding text		surrounding text
	</pre>		</pre>

			=== Verbatim source code ===

			Verbatim [http://www.sphinx-doc.org/en/stable/rest.html#source-code '''code blocks'''], e.g., for code examples, requires double colon at the end of a line, then an empty line, and then the code block itself, indented:

	Bad:		Bad:
	<pre>		<pre>
	- foo		This does not work as there is a single column and no empty line before code:
	~~- nested lists also requires empty lines~~		def foo(bar, baz):
	~~- inner list 1~~		qux = bar + baz
	~~- inner list 2~~
	~~- outer list continues here~~		return qux
	</pre>		</pre>

	~~=== Verbatim source code ===~~		Good:

	~~Verbatim [http~~://www.sphinx-doc.org/en/stable/rest.html#source-code '''code blocks'''], e.g., for code examples, requires double colon at the end of a line, then an empty line, and then the code block itself, indented:

	<pre>		<pre>
	a nice example of python code follows::		a nice example of python code follows::
Line 72:		Line 82:
	'''Inline code samples''' use double backquotes, and not single ones.		'''Inline code samples''' use double backquotes, and not single ones.

	~~Good~~:		Bad:
	<pre>		<pre>
	you have to instantiate the method ``def foo(bar): pass`` in order to use this abstract class		you have to instantiate the method `def foo(bar): pass` in order to use this abstract class
	</pre>		</pre>

	~~Bad~~:		Good:
	<pre>		<pre>
	you have to instantiate the method `def foo(bar): pass` in order to use this abstract class		you have to instantiate the method ``def foo(bar): pass`` in order to use this abstract class
	</pre>		</pre>

Line 92:		Line 102:
	Entries in Args section do ''not'' start with bullets, but just with argument names (as any other Napoleon section).		Entries in Args section do ''not'' start with bullets, but just with argument names (as any other Napoleon section).
	Continuation lines should be indented.		Continuation lines should be indented.

			Bad:
			<pre>
			Args:
			- foo (int): first argument
			- bar: second argument
			- baz (bool): third argument
			</pre>

	Good:		Good:
Line 100:		Line 118:
	long description of what it does		long description of what it does
	baz (bool): third argument		baz (bool): third argument
	~~</pre>~~

	~~Bad:~~
	~~<pre>~~
	~~Args:~~
	~~- foo (int): first argument~~
	~~- bar: second argument~~
	~~- baz (bool): third argument~~
	</pre>		</pre>

Line 114:		Line 124:
	In Returns section you need to use ":" carefully as, if present, it will be interpreted as a separator between return type and description. Also, the description of return value should not start on the same line of "Returns:", but on the subsequent one, indented.		In Returns section you need to use ":" carefully as, if present, it will be interpreted as a separator between return type and description. Also, the description of return value should not start on the same line of "Returns:", but on the subsequent one, indented.

	~~Good~~:		Bad:
	<pre>		<pre>
	Returns:		Returns:
	this ~~works~~, a dict with keys		this does not work (colon will be interpreted as type/desc separator), a dict with keys:

	- foo		- foo
	- bar		- bar
	</pre>		<pre>

	~~Bad~~:		Good:
	<pre>		<pre>
	Returns:		Returns:
	this ~~does not work,~~ a dict with keys:		this works (there is no colon) a dict with keys

	- foo		- foo
	- bar		- bar
	<pre>		</pre>

	Good:		Good:
	<pre>		<pre>
	Returns:		Returns:
	~~dicts~~: this works again, a dict with keys:		dict: this works again (''first'' colon identifies the type) a dict with keys:

	- foo		- foo

StefanoZacchiroli: /* Napoleon */ add gotcha: Args sections

2017-09-07T13:50:46Z

Napoleon: add gotcha: Args sections

← Older revision		Revision as of 13:50, 7 September 2017
Line 87:		Line 87:

	See the [http://www.sphinx-doc.org/en/stable/ext/napoleon.html#docstring-sections list of docstring sections] supported by Napoleon. Everything else will ''not'' be typeset with a dedicated heading, you will have to do so explicitly using reStructuredText markup.		See the [http://www.sphinx-doc.org/en/stable/ext/napoleon.html#docstring-sections list of docstring sections] supported by Napoleon. Everything else will ''not'' be typeset with a dedicated heading, you will have to do so explicitly using reStructuredText markup.

			=== Args ===

			Entries in Args section do ''not'' start with bullets, but just with argument names (as any other Napoleon section).
			Continuation lines should be indented.

			Good:
			<pre>
			Args:
			foo (int): first argument
			bar: second argument, which happen to have a fairly
			long description of what it does
			baz (bool): third argument
			</pre>

			Bad:
			<pre>
			Args:
			- foo (int): first argument
			- bar: second argument
			- baz (bool): third argument
			</pre>

	=== Returns ===		=== Returns ===

StefanoZacchiroli: add See also section, pointing to the Python style guide

2017-09-07T13:27:22Z

add See also section, pointing to the Python style guide

← Older revision		Revision as of 13:27, 7 September 2017
Line 123:		Line 123:
	Returns: this is not good either, you need to start a paragraph		Returns: this is not good either, you need to start a paragraph
	</pre>		</pre>

			== See also ==

			* [[Python style guide]]


	[[Category:Guidelines]]		[[Category:Guidelines]]
	[[Category:Software development]]		[[Category:Software development]]
	[[Category:Python]]		[[Category:Python]]